Defame1297
40ff89eabf
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
2.7 KiB
grill-with-docs
The grilling interview, run against the project's domain model — and writing decisions back into CONTEXT.md and ADRs as they land.
What it does
Runs the same relentless one-question-at-a-time interview as grill-me, with the project's own documentation as an active participant. During codebase exploration it also locates the domain documentation — a root CONTEXT.md and docs/adr/, or a CONTEXT-MAP.md pointing at per-context glossaries and ADR directories in a multi-context repo — and then uses it five ways:
- Challenges terms against the glossary. When the user's usage conflicts with what
CONTEXT.mdalready defines, that is raised immediately rather than absorbed. - Sharpens fuzzy language by proposing a precise canonical term ("you're saying 'account' — do you mean the Customer or the User?").
- Stress-tests domain relationships with concrete scenarios, inventing edge cases that force the user to be precise about where one concept ends and the next begins.
- Cross-references claims against the code, and surfaces contradictions between what the user says happens and what the code does.
- Updates
CONTEXT.mdinline, the moment a term is resolved, rather than batching changes to the end of the session where they get lost.
Files are created lazily — only when there is something real to write.
ADRs are offered sparingly, and only when all three tests pass: the decision is hard to reverse, it would surprise a future reader without the context, and it was a genuine trade-off with real alternatives. Missing any one of the three means no ADR.
Composition
grill-me is the same interview without the documentation side effects — use it when there is no domain model to defend or nothing should be written down yet. triage composes this skill (not grill-me) at step 4 when an issue needs fleshing out. improve-codebase-architecture runs its own grilling loop and borrows this skill's CONTEXT.md and ADR discipline for the decisions that come out of it.
Usage
/grill-with-docs
Describe the plan or design. Expect questions one at a time, each with a recommended answer, and expect CONTEXT.md to be edited during the session rather than after it.
Files
| File | Purpose |
|---|---|
SKILL.md |
The interview instruction plus the domain-awareness rules: file layout discovery, the five during-session behaviours, and the three-part ADR test |
CONTEXT-FORMAT.md |
Skill-root document, cited when a term is resolved: the structure of a CONTEXT.md and how to write a Language entry |
ADR-FORMAT.md |
Skill-root document, cited when an ADR is offered: docs/adr/ naming, sequential numbering, and the ADR template |