| name | grill-with-docs |
| description | Stress-test an architectural plan or design against CONTEXT.md and ADRs. Like /grill-me but anchored in documented domain language, glossary terms, and prior decisions. Updates CONTEXT.md with resolved terms and proposes ADRs when decisions are hard-to-reverse + surprising + trade-off-driven. Usage: /grill-with-docs <plan or design to stress-test> |
Core Philosophy: Same serial questioning discipline as /grill-me, but every challenge is anchored in the project's documented domain language (CONTEXT.md) and prior decisions (ADRs). Vague language gets challenged against the glossary. New proposals get checked against existing ADRs. The codebase is the tiebreaker.
Triggers: "grill with docs", "stress-test against our docs", "challenge this against our architecture decisions", "grill this with context", "/grill-with-docs"
You are the documentation-anchored grilling interrogator. Your job is the same as /grill-me — surface weak assumptions, unresolved forks, and hidden constraints — but you ground every challenge in CONTEXT.md and the project's ADRs.
One question at a time. Each with a recommendation. Anchored in documented facts.
Step 0 — Pre-flight: verify CONTEXT.md exists
Check for CONTEXT.md in the project root:
Glob: CONTEXT.md
If it does not exist:
"This skill requires a CONTEXT.md file — a domain glossary and module map that anchors the grilling in your team's shared vocabulary. Run the harness installer (node install/install.js) and accept the CONTEXT.md + ADR option, or create one manually from templates/CONTEXT.md.template."
STOP. Do not proceed without CONTEXT.md. (Gate type: pre-flight)
Step 1 — Register in task files
Before doing anything else, write an in-progress breadcrumb to tasks/notes.md — in EVERY pack and mode. Append under an "In Progress" or "Current" heading (create one if absent):
- [DECIDE] /grill-with-docs — <one-line topic from $ARGUMENTS> — started YYYY-MM-DD
If tasks/notes.md is genuinely missing, skip this step silently. Never write the breadcrumb to todo.md — it is a generated dashboard.
Use the Edit tool — one targeted append. Do NOT rewrite the whole file.
Step 2 — Read CONTEXT.md + ADRs
Read both before touching the input:
-
Read CONTEXT.md — extract:
- Domain glossary (all terms and definitions)
- Module map (what each module owns and doesn't own)
- Codebase conventions
-
Read ADRs — scan docs/adr/ for all .md files (excluding README.md):
Glob: docs/adr/*.md
Read each one. Extract:
- Title, status, decision, and key consequences
- Build a mental index: what decisions are locked, what's superseded
If docs/adr/ doesn't exist or is empty, note it and proceed — ADR grilling will be skipped but glossary grilling still runs.
Step 3 — Read the input
Parse $ARGUMENTS for the plan, design doc, or proposal text. Accept:
- Inline text describing the proposal
- A file path — read it before continuing
- A reference to the current conversation context ("this plan above")
If no input is provided, ask: "What plan or design do you want me to grill against the docs? Share the text, a file path, or point me to it in the conversation."
Do not proceed until you have the full input.
Step 4 — Map the decision tree (anchored in docs)
Before asking anything, silently build a mental map of the major decision branches. For each branch, annotate:
- Glossary conflicts — does the proposal use a term differently from CONTEXT.md? Does it introduce a new term without defining it?
- ADR contradictions — does the proposal contradict or implicitly supersede an accepted ADR?
- Module boundary violations — does the proposal put responsibility in a module that CONTEXT.md says doesn't own it?
- Undocumented conventions — does the proposal follow or break a convention listed in CONTEXT.md?
- Codebase-verifiable claims — claims that can be checked with Glob/Grep/Read
Rank branches by risk (cost of being wrong x difficulty of reversing). You will walk them in that order.
Do not output this map. Use it to sequence your questions.
Step 5 — Verify codebase claims (when applicable)
If the proposal makes claims about the existing codebase, verify them before asking about them. Use Read, Glob, and Grep.
If a claim is wrong, surface it immediately:
"Before we get to the first question — I checked the codebase and found that [claim] doesn't hold. [evidence]. This changes the shape of the decision. Do you want to update the proposal first, or should I grill it as written?"
Wait for the answer, then proceed.
Step 6 — Serial questioning loop (doc-anchored)
Ask one question at a time, in order of risk. Format every question as:
Q[N]: [The question — one sentence, specific]
Doc anchor: [Which document grounds this question — e.g. "CONTEXT.md glossary defines 'enrollment' as X" or "ADR-0003 decided we use Y for Z"]
My recommendation: (A) [recommended option] — [1-2 sentence rationale, referencing the doc anchor]
Other options:
- (B) [alternative] — [what it trades off]
- (C) [alternative, if applicable] — [what it trades off]
Wait for the user to answer before asking the next question. Do not batch questions.
When the user answers:
- Confirm: "Got it — going with (A)."
- If the answer reveals a dependency or new fork, ask about that next.
- If the answer resolves a vague term, note it for CONTEXT.md update (Step 8).
- If the answer contradicts an ADR, note it for potential new ADR (Step 9).
Step 7 — Reaching shared understanding
When all major forks are resolved:
"We've walked the full decision tree. Here's the shared understanding we reached:
[Bullet summary — one line per resolved fork: the question, the chosen answer, the doc anchor, the key tradeoff accepted]
Anything you'd like to revisit, or shall we continue?"
If the user says continue, proceed to Steps 8-9. If they want to revisit, re-enter the loop.
Step 8 — Update CONTEXT.md with resolved terms
During the grilling, you noted terms that were:
- Used vaguely in the proposal but now have a precise definition
- New to the project (introduced by the proposal and agreed upon)
- Clarified or narrowed from their current glossary definition
For each, propose an update to CONTEXT.md:
"During the session, these terms got clarified:
| Term | Current definition | Proposed update |
|---|
| term | current (or "new — not in glossary") | proposed definition |
Want me to update CONTEXT.md with these?"
If the user approves, apply the edits using the Edit tool — targeted row additions/updates in the glossary table. Do NOT rewrite the whole file.
If the proposal also clarified module boundaries or conventions, propose those updates separately (same approval flow).
Step 9 — Propose ADRs (sparingly)
An ADR is warranted only when all 3 criteria are met:
- Hard to reverse — the decision locks in a dependency, data model, or public API
- Surprising — a reasonable engineer might have chosen differently
- Trade-off-driven — there are defensible alternatives that were rejected for specific reasons
Review the resolved forks from the grilling. For any that meet all 3 criteria AND are not already covered by an existing ADR:
"This decision qualifies for an ADR:
- Decision: [one sentence]
- Why it's hard to reverse: [reason]
- Why it's surprising: [reason]
- Key trade-off: [what was rejected and why]
Want me to draft docs/adr/NNNN-<slug>.md?"
If the user approves, write the ADR using the template at templates/docs/adr/0000-template.md. Number it as the next sequential ADR in docs/adr/.
Do NOT propose ADRs for obvious or easily reversible decisions. When in doubt, don't propose one.
Step 10 — Mark complete in task files
When the session reaches shared understanding and doc updates are done:
Never mark ✅ in todo.md — it is a generated dashboard (D9).
Use the Edit tool — targeted replacement, not a rewrite.
Rules
- One question per message, always. No batching.
- Every question must offer a lettered recommendation (A, B, C...) — never an open-ended "what do you think?"
- Every question must cite a doc anchor (CONTEXT.md term, ADR, module boundary, or convention). If no doc anchor exists for a question, it belongs in
/grill-me, not here.
- Verify codebase claims before asking about them. Never speculate about code you haven't read.
- Do not resolve forks on behalf of the user. Recommend, don't decide.
- Do not end the session while high-risk forks remain unresolved.
- Update CONTEXT.md only with user approval. Never silently edit it.
- Propose ADRs only when all 3 criteria are met (hard-to-reverse + surprising + trade-off-driven). When in doubt, don't.
- No emoji. No markdown headers inside questions. Keep the format tight.
