Grill Me

Derived from Matt Pocock's grill-me (MIT). Matt's interview discipline preserved verbatim. v2.0: docs-anchored mode merged in from Matt's grill-with-docs (MIT) — CONTEXT.md/ADR anchoring plus 3 stdlib validators. Two modes, one skill.

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.

If a question can be answered by exploring the codebase, explore the codebase instead.

Mode Selection

Trigger	Mode
"grill me", stress-test a plan/design, /cs:grill-me	plain — walk the decision tree, no doc persistence
"grill with docs", stress-test against CONTEXT.md/ADR, /cs:grill-with-docs	docs-anchored — same interview + challenge glossary, update CONTEXT.md/ADR inline

Rules (preserved + amplified)

1. One question per turn. Never bundle.
2. Provide a recommended answer with each question. Defaulting to "what do you think?" is lazy.
3. Explore the codebase before asking. If grep / Read resolves it, do that first. Saves a turn.
4. Walk the tree depth-first. Finish a branch before opening another.
5. Track dependencies. If decision B depends on decision A, ask A first.

Workflow (plain mode)

1. User provides a plan or design (or path to one).
2. Run scripts/decision_tree_extractor.py to extract branches.
3. Run scripts/question_generator.py to produce the question list with recommendations.
4. Start a session: scripts/grill_session_tracker.py --action start.
5. Walk the tree, one question at a time, recording answers in the session.
6. When all branches resolved: report "shared understanding reached" + the locked-in decisions.

Workflow (docs-anchored mode)

The same interview loop, plus documentation anchoring. During codebase exploration also look for existing documentation:

/
├── CONTEXT.md                ← domain glossary (the language of the project)
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

If a CONTEXT-MAP.md exists at the root, the repo has multiple contexts — the map points to where each one lives. Create files lazily: only when you have something to write. If no CONTEXT.md exists, create one when the first term is resolved. If no docs/adr/ exists, create it when the first ADR is needed.

0. Pre-flight (before the first question)

• Run scripts/context_md_linter.py CONTEXT.md if a CONTEXT.md exists — confirms the glossary is well-formed before grilling against it.
• Run scripts/adr_scanner.py docs/adr/ if docs/adr/ exists — surfaces numbering gaps, malformed ADRs, status-frontmatter inconsistencies.
• Run scripts/glossary_code_consistency.py --context CONTEXT.md --code src/ — flags defined-but-unused terms (dead glossary) and code-only common nouns that may need definitions. Use these flags as opening grill questions.

During the session

• Challenge against the glossary: when the user uses a term that conflicts with the existing language in CONTEXT.md, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
• Sharpen fuzzy language: when the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User?"
• Discuss concrete scenarios: stress-test domain relationships with specific scenarios that probe edge cases and force precision about boundaries.
• Cross-reference with code: when the user states how something works, check whether the code agrees. Surface contradictions: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
• Update CONTEXT.md inline: when a term is resolved, update CONTEXT.md right there (format in CONTEXT-FORMAT.md). Don't batch — capture as they happen. CONTEXT.md is a glossary and nothing else: no implementation details, not a spec, not a scratch pad.
• Offer ADRs sparingly: only when all three are true — (1) hard to reverse, (2) surprising without context, (3) the result of a real trade-off. If any is missing, skip the ADR. Format in ADR-FORMAT.md.
• When a term is sharpened: edit CONTEXT.md immediately; re-run context_md_linter.py if the edit is structural. When an ADR is warranted: write it under docs/adr/; re-run adr_scanner.py to confirm numbering.

Closing

• Final glossary_code_consistency.py run to confirm no new orphan terms were introduced.
• Summarize: terms added/refined, ADRs written, scenarios discussed, open items.

Output Pattern

Per question turn (both modes):

Q[i]/[total]: [question]
Recommended answer: [your call + 1-sentence rationale]

(Or: I explored the codebase and found [evidence]. Confirm?)

Tooling

See references/companion_tooling.md. Tools: extractor + generator + tracker (plain mode), linter + scanner + consistency (docs mode). Agents: cs-grill-master, cs-grill-with-docs. Commands: /cs:grill-me, /cs:grill-with-docs.

Plain-mode tools

Tool	Role
scripts/decision_tree_extractor.py	Extract decision branches from a plan
scripts/question_generator.py	Produce question list with recommendations
scripts/grill_session_tracker.py	Track session state and recorded answers

Docs-mode tools (stdlib-only)

Tool	Role
scripts/context_md_linter.py	Validate CONTEXT.md against CONTEXT-FORMAT.md structure. PASS/WARN/FAIL per rule.
scripts/adr_scanner.py	Walk docs/adr/, check NNNN-slug.md pattern, numbering integrity, body completeness.
scripts/glossary_code_consistency.py	Cross-reference bold terms in CONTEXT.md against codebase usage. Flag dead glossary + code-only common nouns.

References

• references/companion_tooling.md — extraction/generation/tracking tools + cs-* wrapper
• references/forcing_question_patterns.md — forcing-question library
• references/when_to_stop_grilling.md — "shared understanding" stopping conditions
• references/ubiquitous_language.md — why a glossary belongs in source control (Evans, Vernon, Khononov, Wlaschin, Brandolini, Avram & Marinescu, Fowler)
• references/adr_practice.md — when an ADR earns its keep (Nygard, Tyree & Akerman, Zimmermann Y-statements, MADR, ThoughtWorks Radar, adr-tools, Backstage)
• references/context_md_as_artifact.md — CONTEXT.md as living artifact (Khononov on language drift, Kernighan on naming, BoundedContext bliki, Confluent on data contracts, Brandolini on EventStorming glossary)
• ADR-FORMAT.md, CONTEXT-FORMAT.md — file format specs for docs-anchored mode

---

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