Files

Defame1297 4f49b2a249 refactor(bin): move non-spec root files into references/ across four skills

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

2026-09-09 19:59:02 +00:00

2.7 KiB

Raw Blame History

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

/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

2.7 KiB Raw Blame History