holocron/plugins/bin/skills/grill-with-docs

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
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