claude-skills/docs/commands/cs-grill-with-docs.md

title	description
/cs-grill-with-docs — Slash Command for AI Coding Agents	/cs:grill-with-docs <path-to-plan> — Start a docs-anchored grilling session. Pre-flights CONTEXT.md + docs/adr/ linters, then interrogates the plan. Slash command for Claude Code, Codex CLI, Gemini CLI.

/cs-grill-with-docs

:material-console: Slash Command :material-github: Source

Command: /cs:grill-with-docs <path-to-plan>

The cs-grill-with-docs persona pre-flights the project's documented language and decisions, then walks the plan one branch at a time — challenging fuzzy terms against CONTEXT.md, surfacing code-vs-glossary contradictions, and writing ADRs only when the 3-criteria gate is met.

When to Run

• Stress-testing a plan that touches an established codebase with documented language
• Onboarding a new feature into an existing bounded context
• Resolving ambiguity introduced by drift between glossary and code
• Pre-mortem on an architectural decision before it lands

When NOT to Run (use /cs:grill-me instead)

• The repo has no CONTEXT.md and no docs/adr/ and you don't want to seed them
• You want a plan-only grill in a vacuum (the docs anchor would add no signal)
• The plan is exploratory / pre-language-decision

The Six Forcing-Question Patterns (Docs-Anchored)

1. Glossary conflict: "CONTEXT.md defines '{term}' as X. You just used it to mean Y. Which is it — or are these two concepts?"
2. ADR contradiction: "ADR-{nnnn} locked in {choice}. Your plan implies {opposite}. Are we superseding, or did the plan drift?"
3. Undefined term: "You said '{term}'. CONTEXT.md doesn't define it. Do you mean {candidate-1}, {candidate-2}, or something new?"
4. Code vs claim: "Your code says X. You just said Y. Which is current state — and which are we changing?"
5. ADR 3-criteria gate: "This decision is reversible in an afternoon. Why does it need an ADR? If 'it doesn't' — skip it."
6. Boundary check: "Which bounded context owns this concept? If two contexts both touch it, what's the contract between them?"

Discipline

• Pre-flight the linters first. Never grill without the docs-state snapshot.
• One question per turn. Never bundle.
• Recommended answer attached. Every question carries a position + rationale.
• Codebase + docs before speculation. grep / Read / lint resolves before asking.
• CONTEXT.md edited inline. No deferred glossary batches.
• ADR 3-criteria gate. Hard-to-reverse + surprising + real-trade-off. All three or skip.

Workflow

# 1. Pre-flight — snapshot the docs state
python ../skills/grill-with-docs/scripts/context_md_linter.py CONTEXT.md
python ../skills/grill-with-docs/scripts/adr_scanner.py docs/adr/
python ../skills/grill-with-docs/scripts/glossary_code_consistency.py \
  --context CONTEXT.md --code src/

# 2. Read the plan
#    Use the linter findings as opening question seeds.

# 3. Walk one question at a time:
#    Persona asks Q1 with recommendation (anchored to docs/code).
#    User answers.
#    Apply edits inline if the answer changes the glossary or warrants an ADR.

# 4. Re-lint after any structural CONTEXT.md edit:
python ../skills/grill-with-docs/scripts/context_md_linter.py CONTEXT.md

# 5. Re-scan after any new ADR:
python ../skills/grill-with-docs/scripts/adr_scanner.py docs/adr/

# 6. At close — final consistency sweep:
python ../skills/grill-with-docs/scripts/glossary_code_consistency.py \
  --context CONTEXT.md --code src/

When to Stop

• Every branch has an answer, AND
• Final lint state is clean (context_md_linter + adr_scanner both PASS), AND
• No new fuzzy terms surfaced in the last 3 turns

Produce a "glossary changes + ADRs + open items" summary at close.

Output Format

Q[i]/[total] (anchor: CONTEXT.md§Language | ADR-0003 | code:src/orders/cancel.ts:42 | plan:L18):

[question]

Recommended: [position] because [rationale grounded in the anchor]

Related

• Agent: cs-grill-with-docs
• Skill: grill-with-docs
• Format specs: ADR-FORMAT, CONTEXT-FORMAT
• Sibling skill: /cs:grill-me (plan-only grill)
• Adjacent: /cs:caveman, /cs:handoff, /cs:write-a-skill

---

Version: 1.0.0 Derived: Matt Pocock's grill-with-docs (MIT) + this repo's wrapper