Defame1297
4f49b2a249
grill-with-docs, improve-codebase-architecture, tdd, and triage kept non-spec markdown files at their skill root, in violation of skill-audit's file-structure.md rule (only SKILL.md/README.md belong at the root; everything else lives in scripts/, references/, assets/ or tests/). A root-level file is invisible to the ADR-0020 dangling-reference gate, which only resolves unqualified `references/...` pointers. - Moved and renamed to lowercase-kebab-case under references/: grill-with-docs (ADR-FORMAT.md, CONTEXT-FORMAT.md), improve-codebase-architecture (DEEPENING.md, INTERFACE-DESIGN.md, LANGUAGE.md), tdd (five files, casing was already fine), triage (AGENT-BRIEF.md, OUT-OF-SCOPE.md). - Updated every in-skill link to the new references/ paths, including link text that still showed the old uppercase filenames. - Fixed improve-codebase-architecture/SKILL.md's cross-skill citation of grill-with-docs's two files to the sanctioned possessive form with the references/ segment included. - Updated all four skills' README.md file tables to match. - Regenerated the flat content mirror via scripts/sync-plugin-content.sh --all. Fixes #122. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PDj6F7SPXzh3FtPN78dZ88
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 |
references/context-format.md |
Cited when a term is resolved: the structure of a CONTEXT.md and how to write a Language entry |
references/adr-format.md |
Cited when an ADR is offered: docs/adr/ naming, sequential numbering, and the ADR template |