Skip to content

/cs-grill-with-docs

Slash Command 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]

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