guidance

Guidance

The user has given new guidance for how you should carry out work. Your job is to:

1. record that guidance durably in the right capability
2. keep the existing rule set internally consistent
3. retroactively fix any work in this session that already violates the new rule

A capability skill (or just capability) is a skill that has type: capability in its frontmatter and a description field that states when it should be adopted. Capabilities are loaded selectively: an agent reads the description of each available capability and adopts only those relevant to the task at hand. The whole system depends on descriptions reliably triggering adoption for the situations they cover and staying silent otherwise — so writing a good description is the single highest-leverage step in this workflow.

Inputs

The user supplies:

• What they want the agent to do or stop doing.
• Why — the rationale. Rationale is required for every rule, but you may infer it from session context (the failure that prompted this guidance is often the rationale). If the user provided one, use it. If they did not and you can infer one clearly from what just happened, draft it and proceed. If you cannot infer one, ask the user.

If the what is ambiguous, ask before proceeding.

Workflow

Follow these steps in order. Do not skip.

1. Understand the rule

Restate the rule to yourself. Identify:

• The triggering situation — when does the rule apply? Name it concretely (e.g. "writing Python tests", "designing a database schema", "integrating Python with SQL"), not as a topic area ("code quality"). This phrase will become the core of the capability's description in step 6.
• The required behavior (do / don't do what?)
• The rationale (why?) — user-provided or inferred.
• The rule must be phrased as generically as the concept allows. Prefer language that would still make sense outside this project, so a project-level rule can later be promoted to user level without rewriting. Exception: if the rule is about a concept that exists only in this project and has no generic analog, use the project's vocabulary — but still phrase the rule "generically within the project," covering every place that concept appears, not one specific call site. If the user gave a concrete example, abstract the rule and keep the example concrete.

2. Find the right capability

First check whether the failure that prompted this guidance happened despite a relevant capability already existing. If a capability covers this situation but was not adopted, the bug is likely in its description, not its rules. Fix the description (see step 6) and stop — do not add a duplicate rule.

If no existing capability covers the situation, check the current project's skills, then the user's skills, and decide:

• Update existing — there is a capability whose triggering situation clearly contains this one. Add a rule to that file.
• Create new — no existing capability covers this situation. Default to project scope. The user may say "user scope" to override, or later ask to promote a project capability to user scope. Name the new capability capability-<concern> (kebab-case), e.g. capability-python-style, capability-sql-migrations. The capability- prefix is mandatory so capability skills are visually distinct from workflow skills.
• Split — the rule belongs to a different concern than the rest of the existing file. Prefer creating a new capability over stretching one. Capabilities should each do one focused thing; complex tasks adopt multiple capabilities that compose (e.g. separate "writing Python", "writing SQL", and "integrating Python with SQL" capabilities).

Splitting decisions are based on scope and concern, not file size. Granular capabilities produce more focused guidance, provided each description reliably triggers adoption.

3. Check for contradictions

Before writing the new rule, scan rules in capabilities whose triggering situations overlap with the new rule's. For each:

• If the new rule directly contradicts an existing rule and the resolution is clear (the user's new guidance supersedes), update or remove the old rule. Note in your response that you did so.
• If the contradiction is unclear, ask the user how to resolve before writing.

Contradiction avoidance happens at write time only. You are not responsible for detecting every possible runtime conflict between capabilities.

4. Write or update the rule

Each rule entry follows this structure:

### <Short imperative title>

**Rule:**

<Description of the rule.>

**Rationale:**

<The rationale for the rule to contextualize the purpose.>

**Good:**
```<lang>
<small example that follows the rule>

Avoid:

<small example that violates the rule, should differ from the good example only in violation of the rule>

Requirements:
- Every rule has a **Rule** and a **Rationale**.
- Every rule has a **Good** and an **Avoid** example where possible. Examples should be small (a few lines) and self-contained.
- Phrase rules as generically as the concept allows. Prefer language that travels outside the project. If the rule names a project-only concept with no generic analog, project vocabulary is allowed — but the rule must still be generic *within the project*, covering every site where the concept appears, not one specific case. Keep examples concrete regardless.
- Imperative voice ("Do X", "Avoid Y") not narrative ("We should...").

Notes:
- Not all rules are about code, so examples do not have to be code blocks.

### 5. Audit examples in the touched capability

After writing the new rule, re-read every example (good and bad) in the capability you edited. For each example, check whether it now violates the new rule. If a "good" example violates the new rule, update it to comply. If a "bad" example now also violates the new rule (and that wasn't its intended demonstration), pick a different bad example so the original lesson stays clear.

If an example cannot be updated without breaking the rule it was originally demonstrating, ask the user how to resolve.

### 6. Write or update the capability's `description`

This step determines whether the capability will be adopted in future sessions. Treat it as the most important step.

The description must:
- Name the **triggering situation** identified in step 1, concretely — task types, file types, or activities, not topic areas.
- **Enumerate every mode in which the capability applies.** Capabilities apply across planning, answering questions, designing, and writing/modifying — not only at the moment code is being written. List the modes explicitly so an agent (or an orchestrator selecting capabilities for a subagent) can decide adoption without inferring.
- Make adoption decidable from the description alone, without reading the rules.
- Stay silent on situations the capability does not cover, so it is not adopted spuriously.

**Good description (enumerates modes):**
> This capability should be adopted when planning Python tests, answering questions about Python test design, reviewing test code, or writing/modifying Python test files (pytest, unittest). Covers test structure, fixture usage, and assertion style.

**Avoid (mode-narrow — misses planning, Q&A, review):**
> Use when writing Python test files. Covers test structure, fixture usage, and assertion style.

**Avoid (too vague — adopted for every task or none):**
> Covers code quality and best practices.

**Avoid (triggers on user words, not on the actual task):**
> Use this when the user mentions tests.

If you arrived here from step 2 because the failure showed an existing capability *should* have been adopted but wasn't, rewrite the description so it would have triggered for that task.

Before moving on, do a mental check: imagine the situation that prompted this guidance. Would an agent reading only this description have chosen to adopt this capability? If no, revise.

### 7. Propagate the capability to existing subagent definitions

Subagents do not perform capability selection at runtime — they only load what is listed in their `skills:` frontmatter (see [[capability-sub-agent]]). A capability that should apply to delegated work is only effective if each relevant subagent definition preloads it.

For every subagent definition in scope (project-level subagents for a project-scoped capability; project + user-level subagents for a user-scoped capability), evaluate whether the subagent's task would adopt this capability under the same selection logic the orchestrator uses. If suitable, add the capability's name to the subagent's `skills:` field (creating the field if absent). If not suitable, leave it alone.

Apply this step on **creation** (add the new capability to relevant subagents) and on **removal** (remove the capability name from every subagent's `skills:` field where it appears, in addition to deleting the capability file itself).

Skip subagents whose definitions you cannot modify (built-in agents like `general-purpose`, `Explore`, `Plan`). For those, the inline-in-prompt fallback in [[capability-sub-agent]] is the only mechanism.

### 8. Retroactively fix recent work in this session

The new rule applies immediately, including to work done earlier in this session. Scan:

- Files you have edited or created in this conversation.
- Plans, designs, or prose you have written in this conversation.
- Tasks in your task list.

Fix violations. Do not expand scope beyond this session — do not audit prior commits, other branches, or unrelated files. If the violation is in something already shipped (committed, pushed, sent), tell the user — do not try to rewrite history without permission.

### 9. Confirm to the user

Report concisely:
- Which capability file you wrote to (path), and whether it was created or updated.
- The triggering situation you encoded in the description.
- Any contradictions you resolved.
- Any examples you updated.
- Any subagent definitions you updated (paths) — added or removed from their `skills:` field.
- Any retroactive fixes you made to session work.

## Capability skill file template

```markdown
---
name: capability-<concern>
description: This capability should be adopted when <concrete triggering situation, enumerating modes>. Covers <short scope summary>.
type: capability
---

# <Title>

<Optional one-paragraph overview of the domain. Skip if the rules are self-explanatory.>

## Rules

### <Rule 1 title>

**Rule:**

<Statement.>

**Rationale:**

<Rationale.>

**Good:**
```<lang>
<example>

Avoid:

<example>

<Rule 2 title>

...

## Constraints to enforce

- **Generic phrasing where possible.** Project-level capabilities are project-scoped by *placement*, not by vocabulary — prefer language that would survive promotion to user level. The one exception: rules about concepts that exist only in this project and have no generic analog may use project vocabulary, but must still be generic *within the project* (covering every site the concept appears, not one specific case). Examples stay concrete regardless.
- **Rationale-first.** A rule without a rationale is incomplete. Infer if you can, ask if you cannot.
- **One rule per entry.** Do not bundle multiple unrelated rules under one heading.
- **One focused concern per capability.** If a rule belongs to a different concern than the rest of the file, split it into a new capability rather than broadening the existing one. Complex tasks compose multiple capabilities.
- **Examples are mandatory.** Good and bad examples for every rule. If you cannot construct a bad example, the rule may be too vague to enforce — sharpen it.
- **Descriptions name situations, not topics.** "When writing SQL migrations" is a situation; "database stuff" is a topic.
- **Naming convention.** Capability skill directories and `name:` values are prefixed `capability-` (e.g. `capability-python-style`). Workflow skills like `guidance` itself do not use the prefix. The prefix makes capability skills visually distinct in skill listings and in subagent `skills:` frontmatter.

## When the user wants to remove a rule

Treat removal the same way: find the rule, delete it, then run step 5 (the removed rule may have been justifying compromises in examples elsewhere) and step 8 (recent work may have been *complying* with a now-removed constraint that you should now reverse). If removing the rule leaves the capability empty or unfocused, consider deleting the capability entirely or merging its remaining rules elsewhere.

If you delete a capability outright, also run step 7 in reverse: scan every subagent definition for the capability name in its `skills:` field and remove it. A dangling reference to a deleted skill produces a startup warning and silently drops the preload.

Confirm to the user what was removed and from where, including any subagent definitions you cleaned up.

## When the user's guidance is ambiguous

Ask. The cost of one clarifying question is small; a wrong rule encoded into capabilities propagates into every future task. Prefer asking over guessing about:
- Which capability the rule belongs in.
- How to phrase the rule generically.
- How to resolve a contradiction with an existing rule.
- Scope (project vs user) if the user signals a non-default preference but doesn't say which.