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
38 lines
2.7 KiB
Markdown
38 lines
2.7 KiB
Markdown
# 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.md` already 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.md` inline**, 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
|
|
|
|
```text
|
|
/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 |
|