fix(bin): restore prototype's deleted anti-patterns and two routing triggers
ADR-0020's stated anti-goal is satisfying the size gate by deleting content rather
than relocating it. prototype's logic.md lost three anti-patterns, including
"Don't generalise" — the one with a distinct failure mode, a throwaway growing
abstractions for hypothetical futures, and the one the logic branch is most exposed
to. It survived nowhere in the repo.
The deletion bought nothing measurable: references/ sits outside the body FAIL,
outside the 600-word suggestion and outside the Vale gate, and prototype's body is
483 words. 4011d14 restored the byte-identical defect in the sibling ui.md with
exactly that reasoning in its message and left this file alone. Restored verbatim
from main.
improve-codebase-architecture had dropped "refactoring" from its description
entirely, so "find refactoring opportunities in this repo" had no lexical match,
while spending characters on a boundary against tdd — which cannot plausibly steal
an architecture request. retrofit.md names that exact failure: an invented boundary
costs characters and buys no routing accuracy.
write-docs had dropped all four literal trigger phrasings, leaving them only in the
body and a `when:` field, neither visible to the router at routing time. Its
boundary also sent PRDs to grill-with-docs, which has no PRD flow, and the body
repeated that at two more places. Per #123 nothing in the corpus produces a PRD, so
no target was invented — the boundary is now honest about the ADR case only.
Two READMEs added by this branch contradicted the SKILL.md they document: triage's
label resolution, and grill-with-docs' fifth during-session behaviour. Unconditional
reference pointers in tdd and improve-codebase-architecture are now conditional; the
files stay at the skill root, which is #122's scope.
Refs: #114, #122, #123
ADR: 0020
This commit is contained in:
@@ -2,8 +2,10 @@
|
||||
name: write-docs
|
||||
description: >
|
||||
Use when the user wants technical documentation produced or updated from code
|
||||
or spec, every claim traced to a source. Not a PRD, ADR, or decision doc ->
|
||||
`grill-with-docs`. Not an external tool researched from its docs -> `research`.
|
||||
or spec, every claim traced to a source — "write docs for X", "document this
|
||||
module", "create docs for this feature", "write a README for this". Not an ADR
|
||||
or other decision record -> `grill-with-docs`. Not an external tool researched
|
||||
from its docs -> `research`.
|
||||
version: "1.0"
|
||||
updated: 2026-05-17
|
||||
when: invoked by explicit trigger ("write docs for X", "document this module", "create docs for this feature") or implicit request to produce technical documentation from code or spec
|
||||
@@ -38,7 +40,8 @@ You are a technical writer that produces documentation by reading code and spec
|
||||
- User says "write docs for X", "document this", "create docs for this feature", "write a README for this"
|
||||
|
||||
**Do not use when:**
|
||||
- User wants a PRD, decision doc, or architecture proposal → `grill-me` or `grill-with-docs`
|
||||
- User wants an ADR, decision doc, or architecture proposal → `grill-with-docs`, which writes ADRs
|
||||
- User wants a PRD → no skill in this set produces one; say so rather than redirecting
|
||||
- User wants to document a skill file (skill files are self-describing)
|
||||
- User wants marketing or blog copy
|
||||
- Documentation requires tacit organisational knowledge that cannot be read from code or spec
|
||||
@@ -91,7 +94,7 @@ You are a technical writer that produces documentation by reading code and spec
|
||||
- Stage skipped without a logged reason → flag and require the one-sentence log before continuing
|
||||
- Code behaviour is undocumentable (internal implementation detail, no public spec) → note as out-of-scope in the doc; do not invent an explanation
|
||||
- Reader Testing sub-agent fails on multiple questions → surface the failures, return to step 4; do not mark complete
|
||||
- Requested output is a PRD, decision doc, or architecture proposal → redirect to `grill-me` or `grill-with-docs`
|
||||
- Requested output is an ADR, decision doc, or architecture proposal → redirect to `grill-with-docs`; for a PRD, say no skill here produces one instead of redirecting
|
||||
|
||||
## Self-check
|
||||
|
||||
|
||||
Reference in New Issue
Block a user