| name | context-distillation |
| description | Turn raw material in docs/context/ into reviewed agreements (requirements with REQ-### IDs, ADRs, glossary, non-goals) and place each piece of knowledge in the right context tier — always-on instructions, path-scoped instructions, or on-demand skills/docs. Use this after collection passes, before planning an Epic, when agents keep missing the same context, or when instruction files grow bloated. |
Context Distillation
Distillation answers two questions for every piece of collected knowledge:
is it true and agreed? and when should an agent see it? The first
produces docs/agreements/; the second decides its tier. Skipping the second
question is the classic failure mode — stuffing everything into always-on
instructions degrades every request a little until agents get worse, not
better.
Outputs
| Artifact | File | Rules |
|---|
| Requirements | docs/agreements/requirements.md | one REQ-### per verifiable statement; IDs never reused |
| Non-goals | docs/agreements/non-goals.md | explicit "we will not" list — the cheapest scope-creep guard |
| Decisions | docs/agreements/adr/ADR-####-<slug>.md | one decision per ADR, template ADR-0000-template.md |
| Vocabulary | docs/agreements/glossary.md | project-specific terms; agents misname what humans leave undefined |
Procedure
- Scope. Pick one topic directory in
docs/context/; read its INDEX.md
and flagged conflicts first.
- Extract candidates. Draft requirement statements, decisions, terms,
and non-goals. Each must trace back to a source file (link it) — a
candidate with no source is an invention and needs human confirmation.
- Resolve conflicts explicitly. Where sources disagree, present the
options; a human picks. Record the pick as an ADR if it is architectural,
or directly as the surviving
REQ otherwise.
- Write the diff, open a PR. Agreements change only via PR with human
approval (
.claude/rules/docs.md). The PR description lists each new/changed
REQ-###/ADR with its source link. Merge = agreement; the review
thread is the negotiation record.
- Tier the knowledge (see below) and, when a tier assignment adds or
changes instruction/skill files, include those edits in the same PR so the
agreement and its delivery mechanism land together.
Tiering: when should an agent see it?
| Tier | Test | Destination | Budget |
|---|
| Always-on | Needed on most tasks, stable, compressible to a few lines | AGENTS.md, CLAUDE.md | keep each file lean — target well under ~150 lines; adding usually means removing |
| Scoped | Needed only when touching certain paths | .claude/rules/<area>.md with paths frontmatter | one concern per file |
| On-demand | Large, procedural, or rarely needed | a skill under .claude/skills/ or a doc under docs/agreements/ referenced from issues | no practical size limit; discoverability via skill descriptions and issue links |
Tie-breakers: if agents repeatedly miss it, promote one tier up; if an
always-on line hasn't mattered in weeks of PRs, demote it. Task-specific
context never goes into instructions at all — it belongs in the Task issue's
"Context & references" section.
Quality bar
- Every
REQ is testable — a verification command or observable behavior can
prove it. "The system should be fast" is not a requirement until it has a
number.
- Agreements are short declarative sentences; rationale lives in the linked
ADR or source, not inline.
- After merging, mark distilled source files'
status: as distilled in
their provenance headers so future passes skip them.
