name: progressive-disclosure
description: "Use when the user asks to remember, add a rule, keep in mind, always/never do something, make sure future agents know something, or otherwise persist guidance/memory."
Progressive Disclosure
Persist agent guidance where it loads only when useful.
Context must be as tiny as possible, as big as needed.
Workflow
Classify intent first.
Decide what the user really wants persisted: rule, preference, workflow, project fact, troubleshooting lesson, domain knowledge, command, or temporary/local note.
Ask only if unclear.
Distill hard.
Convert chat into the smallest durable instruction.
Prefer one concrete imperative bullet over explanation.
Preserve exact commands, paths, and safety constraints.
Never persist secret values; store only non-secret handling rules, paths, and procedures.
Find the right mechanism.
Inspect relevant existing instruction/memory files before proposing a target.
Do not assume a wiki, memory dir, or one harness.
Use the discovered project/user conventions.
Choose by fit, not fixed priority.
Evaluate audience, scope, lifetime, activation cost, shareability, sensitivity, and whether the content is instruction or fact.
Check consistency.
Compare the new instruction with existing active rules and nearby memory.
If it conflicts, stop and ask which rule wins.
If it duplicates or weakens an existing rule, propose the minimal patch instead of appending noise.
Propose before writing.
Show target path(s), exact text/diff per target, rationale, and any split across files.
Write only after explicit user approval.
Patch minimally.
Patch the shortest coherent section.
Append when no matching section exists.
Deleting misleading rules is more valuable than adding new ones.
If you can leave existing rules shorter, bt keep new desired baehaviour, do so.
Edit existing text to remove duplication, fix conflict, or keep a section coherent, and only with approval.
Read references/placement-examples.md when the user asks for examples or placement is ambiguous.
Placement heuristics
Agent behavior rule for everyone in a repo → nearest applicable AGENTS.md/equivalent context file.
Subtree-specific rule → AGENTS.md/equivalent in that subtree, not repo root.
Personal cross-project agent preference → user/global agent instructions.
Multi-step conditional workflow → skill, command, or playbook loaded on demand.
Long reference or examples → referenced file, not always-loaded instructions.
Factual research/lesson → discovered cheap file-based memory/notes/docs system, not an instruction file unless it changes agent behavior.
Secret, machine-local, or private setup → local ignored file if the project has one; otherwise ask. Never store secret values.
Output contract
Before approval, output:
Intent: <minimal classification>
Target(s): <path or paths>
Patch: <exact text or diff per target>
Why here: <one sentence>
Conflicts: <none | summary + choice needed>
After approval, write exactly the approved patch and report touched paths.
---
name: progressive-disclosure
description: "Use when the user asks to remember, add a rule, keep in mind, always/never do something, make sure future agents know something, or otherwise persist guidance/memory."
---
# Progressive Disclosure
Persist agent guidance where it loads only when useful.
Context must be as tiny as possible, as big as needed.
## Workflow
1. **Classify intent first.**
Decide what the user really wants persisted: rule, preference, workflow, project fact, troubleshooting lesson, domain knowledge, command, or temporary/local note.
Ask only if unclear.
2. **Distill hard.**
Convert chat into the smallest durable instruction.
Prefer one concrete imperative bullet over explanation.
Preserve exact commands, paths, and safety constraints.
Never persist secret values; store only non-secret handling rules, paths, and procedures.
3. **Find the right mechanism.**
Inspect relevant existing instruction/memory files before proposing a target.
Do not assume a wiki, memory dir, or one harness.
Use the discovered project/user conventions.
4. **Choose by fit, not fixed priority.**
Evaluate audience, scope, lifetime, activation cost, shareability, sensitivity, and whether the content is instruction or fact.
5. **Check consistency.**
Compare the new instruction with existing active rules and nearby memory.
If it conflicts, stop and ask which rule wins.
If it duplicates or weakens an existing rule, propose the minimal patch instead of appending noise.
6. **Propose before writing.**
Show target path(s), exact text/diff per target, rationale, and any split across files.
Write only after explicit user approval.
7. **Patch minimally.**
Patch the shortest coherent section.
Append when no matching section exists.
Deleting misleading rules is more valuable than adding new ones.
If you can leave existing rules shorter, bt keep new desired baehaviour, do so.
Edit existing text to remove duplication, fix conflict, or keep a section coherent, and only with approval.
Read `references/placement-examples.md` when the user asks for examples or placement is ambiguous.
## Placement heuristics
- Agent behavior rule for everyone in a repo → nearest applicable `AGENTS.md`/equivalent context file.
- Subtree-specific rule → `AGENTS.md`/equivalent in that subtree, not repo root.
- Personal cross-project agent preference → user/global agent instructions.
- Multi-step conditional workflow → skill, command, or playbook loaded on demand.
- Long reference or examples → referenced file, not always-loaded instructions.
- Factual research/lesson → discovered cheap file-based memory/notes/docs system, not an instruction file unless it changes agent behavior.
- Secret, machine-local, or private setup → local ignored file if the project has one; otherwise ask. Never store secret values.
## Output contract
Before approval, output:
```text
Intent: <minimal classification>
Target(s): <path or paths>
Patch: <exact text or diff per target>
Why here: <one sentence>
Conflicts: <none | summary + choice needed>
```
After approval, write exactly the approved patch and report touched paths.