Defame1297
4011d149bc
grill-me, grill-with-docs, improve-codebase-architecture, tdd and triage each had their routing boundary written into README.md, which nothing loads at runtime, while the gate still reported all five descriptions as boundary-less. The boundaries move into the descriptions; write-docs' clause, which said 'those have dedicated skills' without naming one, now names them. research had moved its body out and then read both references unconditionally -- the anti-goal ADR-0020 names, where the word count moves and the per-run context does not. Both loads are genuinely conditional now, with the topic list and the four literal sources.md field names inlined, since the provenance validator matches those literally. Also restores the promote-the-prototype anti-pattern to prototype's ui.md, which the gate does not measure, so deleting it bought nothing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EJJrm5YmacbwMdzZpXcoti
write-docs
Produce technical documentation derived from code and spec, one section at a time, with a confirmation gate on every section.
What it does
Casts the agent as a technical writer with one non-negotiable constraint: every claim must be traceable to a source file line, a spec section, or an explicit user statement. Nothing is invented, and behaviour that genuinely cannot be documented from the available sources is marked out-of-scope rather than explained away.
The process is eight steps — identify scope, read and extract, gap check, draft section by section, confirmation gate, delta summary, reader testing, finalise — and several of them are deliberately gated on the human:
- Files are read only after the user approves them by name. The skill may propose candidates; it waits.
- The gap check presents what the code does say and asks the user to fill only what it does not: caller intent, error-handling rationale, non-obvious side effects.
- No section is finalised until the full revised text has been shown. The skill never gates on output the user has not seen, and never reprints the whole document — all edits are surgical.
- Reader testing predicts 5–10 questions a target reader would ask, then spawns a sub-agent that receives only the finished doc and the questions — no source files. If the doc cannot answer them, neither can the sub-agent, and the run loops back to drafting.
Summary and overview sections are written last, once the detail sections are stable.
Usage
/write-docs
Name the files or modules to document, the target audience (developer / user / contributor / internal), and the documentation type (reference, guide, README section, inline comment, changelog entry). For a PRD, ADR or decision doc, use grill-me or grill-with-docs instead — those have dedicated handling.
Files
| File | Purpose |
|---|---|
SKILL.md |
The whole skill — role, use/do-not-use boundaries, required inputs, constraints, the eight-step process, output format, failure handling, and a nine-item self-check |