Docs-anchored grilling session. Walks the decision tree of a plan one branch at a time, but does so against the project's existing language (CONTEXT.md) and recorded decisions (docs/adr/). Sharpens terminology + records architecturally-significant decisions inline as they crystallise.

Attribution

Derived from Matt Pocock's grill-with-docs (MIT, © 2026 Matt Pocock). Matt's interview discipline + domain-awareness rules preserved verbatim per his MIT license — relentless one-question-at-a-time grilling, codebase-and-docs-first exploration, the three-criterion gate for offering an ADR (hard-to-reverse + surprising-without-context + real-trade-off).

How this differs from `grill-me`

Aspect	`grill-me`	`grill-with-docs`
Grounding	Plan text only	Plan + `CONTEXT.md` + `docs/adr/` + codebase
Output	Session notes	Session notes plus inline updates to CONTEXT.md and (when warranted) new ADRs
Question source	Decision tree extracted from plan	Decision tree plus language conflicts, fuzzy terms, code-vs-glossary contradictions
When to use	Stress-testing a fresh plan	Onboarding a plan into an established codebase with documented language

Both ship as separate plugins; pick whichever matches the situation. The grill-me skill is plan-only; grill-with-docs is plan + project memory.

What this adds on top of Matt's original

Addition	Where	Why
3 stdlib Python tools	`skills/grill-with-docs/scripts/`	Lint CONTEXT.md format · Walk docs/adr/ for numbering + body integrity · Cross-reference bold terms in CONTEXT.md against codebase usage (dead glossary + code-only common nouns)
3 in-depth references (7+ sources each)	`skills/grill-with-docs/references/`	Ubiquitous language canon · ADR practice canon · CONTEXT.md as living artifact
cs-grill-with-docs persona agent	`agents/cs-grill-with-docs.md`	Docs-aware grill voice; pre-flights the linters before the first question
`/cs:grill-with-docs` slash command	`commands/cs-grill-with-docs.md`	Activation + workflow handoff

Matt's original (preserved)

"Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. Ask the questions one at a time, waiting for feedback on each question before continuing. If a question can be answered by exploring the codebase, explore the codebase instead."

"Only offer to create an ADR when all three are true: hard to reverse, surprising without context, the result of a real trade-off. If any of the three is missing, skip the ADR."

Quick start

# 1. Lint existing CONTEXT.md (if present)
python skills/grill-with-docs/scripts/context_md_linter.py CONTEXT.md

# 2. Scan existing ADRs (if present)
python skills/grill-with-docs/scripts/adr_scanner.py docs/adr/

# 3. Cross-reference glossary terms against codebase
python skills/grill-with-docs/scripts/glossary_code_consistency.py \
  --context CONTEXT.md --code src/

# 4. Use /cs:grill-with-docs to start the session

License

MIT (matching Matt's upstream).

README.md

grill-with-docs