| name | write-docs |
| description | Capture an already-settled design into CONTEXT.md glossary terms and ADRs. Use when the user says "write the docs for this", "capture this in CONTEXT.md", or "record this decision as an ADR". |
Capture an already-settled understanding into documentation. The decisions are
made and the terms are agreed — write them down, do not re-litigate them. Take
that understanding from the current conversation, a finished design discussion,
or a merged decision, and record it:
No grilling. Do not run an interview loop, walk the design tree one question
at a time, or invent edge cases to force precision — that work is out of scope
here. If a fact can be checked in the codebase, check it instead of asking.
Find the documentation layout
Most repos have a single context:
/
├── CONTEXT.md
├── docs/
│ └── adr/
│ ├── 0001-event-sourced-orders.md
│ └── 0002-postgres-for-write-model.md
└── src/
If a CONTEXT-MAP.md exists at the root, the repo has multiple contexts and the
map points to where each one lives (see CONTEXT-FORMAT.md).
When multiple contexts exist, infer which one the current topic belongs to; if it
is unclear, ask which context to write into.
Create files lazily — only when you have something to write. If no CONTEXT.md
exists, create one when the first term is captured. If no docs/adr/ exists,
create it when the first ADR is needed.
What to capture
Update CONTEXT.md
When a term is settled, write it into CONTEXT.md using the
CONTEXT-FORMAT.md rules: an opinionated canonical term, a
tight one-or-two-sentence definition, and an _Avoid_ list of the rejected
synonyms.
CONTEXT.md is a glossary and nothing else. Keep it totally devoid of
implementation details — it is not a spec, a scratch pad, or a place for
implementation decisions.
Challenge a conflicting term
Before writing a term, check it against the existing glossary. If it conflicts
with language already in CONTEXT.md, surface the conflict rather than silently
adding a synonym or a contradiction: "Your glossary defines 'cancellation' as X,
but this seems to mean Y — which should it be?"
Sharpen a fuzzy term
If a term is vague or overloaded, propose the precise canonical choice before
writing it: "This says 'account' — is that the Customer or the User? Those are
different things." Write the sharpened term, not the fuzzy one.
Cross-reference with code (lightly)
Do a light sanity check against the code before recording something — just
enough to catch a claim the code plainly contradicts, never an exhaustive audit.
Surface any clear contradiction: "The code cancels entire Orders, but this says
partial cancellation is possible — which is right?"
Offer ADRs sparingly
Only offer to record an ADR when all three are true:
- Hard to reverse — the cost of changing your mind later is meaningful.
- Surprising without context — a future reader will wonder "why this way?"
- The result of a real trade-off — there were genuine alternatives and one
was chosen for specific reasons.
If any of the three is missing, skip the ADR. Use the
ADR-FORMAT.md rules for the file itself.
A repo may override the ADR file-naming scheme (for example, naming an ADR
after its originating issue). When the repo documents its own scheme, follow
the repo; otherwise use the default in ADR-FORMAT.md.
Attribution
The bundled CONTEXT-FORMAT.md and
ADR-FORMAT.md are copied verbatim from the domain-modeling
skill in mattpocock/skills. This skill
runs only the documentation-writing half — domain-modeling's capture — without
the grilling interview.
