Grill With Docs

Purpose

Drive a relentless interview that challenges the user's plan against the project's existing domain model: the glossary in CONTEXT.md and the architectural decisions in docs/adr/. Sharpen fuzzy terms, surface contradictions between the plan and the code, and update the docs inline as terms and decisions resolve — capturing them as they happen, not in a batch at the end.

Workflow

1. Locate the Domain Documentation

   • Look at the repo root and the area being discussed for existing docs
   • IF: CONTEXT-MAP.md exists at the root → the repo has multiple contexts; read the map to find which context the topic belongs to
   • IF: only a root CONTEXT.md exists → single-context repo, use it
   • IF: neither exists → no docs yet; create them lazily later (only when the first term or decision crystallises)
   • Also look for docs/adr/ to see what decisions are already recorded
   • Expected layout for a single-context repo:

     /
     ├── CONTEXT.md
     ├── docs/
     │   └── adr/
     │       ├── 0001-event-sourced-orders.md
     │       └── 0002-postgres-for-write-model.md
     └── src/
     

   • Expected layout for a multi-context repo (decisions live per-context, system-wide decisions live at the root):

     /
     ├── CONTEXT-MAP.md
     ├── docs/adr/                          ← system-wide decisions
     ├── src/
     │   ├── ordering/
     │   │   ├── CONTEXT.md
     │   │   └── docs/adr/                  ← context-specific decisions
     │   └── billing/
     │       ├── CONTEXT.md
     │       └── docs/adr/
     

   • IF: multiple contexts exist and the relevant one is unclear → ask the user which context the topic belongs to

2. Interview One Question at a Time

   • Walk each branch of the design tree, resolving dependencies between decisions one by one
   • Exactly one question per turn — never batch
   • Pair each question with your recommended answer so the user can react quickly
   • Wait for the user's reply before moving on
   • IF: a question can be answered by exploring the codebase → explore the code instead of asking the user, then report the finding
   • Example: "I see OrderService.cancel() deletes the row outright. My recommended answer: cancellation is a hard delete. Is that what you mean, or do you want a soft cancelled state?"

3. Challenge Against the Glossary

   • When the user uses a term that conflicts with the existing language in CONTEXT.md, call it out immediately
   • Quote the existing definition and ask which meaning they intend
   • Example: "Your glossary defines 'cancellation' as removing the order from the queue, but you seem to mean refunding a paid order. Which is it — and should the glossary entry change?"

4. Sharpen Fuzzy Language

   • When the user uses vague or overloaded terms, propose a precise canonical term
   • Make the alternatives explicit so the user can pick
   • Example: "You're saying 'account' — do you mean the Customer (a person who places orders) or the User (a login identity)? Those are different things in your domain."

5. Stress-Test With Concrete Scenarios

   • When domain relationships are being discussed, invent specific scenarios that probe edge cases and force precision about the boundaries between concepts
   • Use scenarios to surface assumptions the user hasn't articulated yet
   • Example: "Say a customer cancels half an order after one item has shipped. Is that one Order in two states, or two Orders? Your answer will dictate the cancellation model."

6. Cross-Reference With Code

   • When the user states how something works, check whether the code agrees
   • IF: you find a contradiction between the stated plan and the actual code → surface it directly
   • Example: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"

7. Update CONTEXT.md Inline When a Term Resolves

   • When a term is resolved, update CONTEXT.md right there in the same turn — do not batch these up
   • IF: CONTEXT.md does not exist yet → create it lazily the moment the first term resolves
   • IF: multi-context repo → write to the CONTEXT.md of the relevant context, not the root
   • Format: see ./references/CONTEXT-FORMAT.md
   • Hard rule: CONTEXT.md is a glossary and nothing else. It must be totally devoid of implementation details. Do not treat it as a spec, a scratch pad, or a repository for implementation decisions.
   • Example: User confirms "Customer = person or org that places orders; Client and Buyer are aliases to avoid." → immediately add a **Customer** entry to CONTEXT.md with that definition and the avoided aliases.

8. Offer ADRs Only When All Three Tests Pass

   • Only offer to create an ADR when ALL of the following are true:
     1. Hard to reverse — the cost of changing your mind later is meaningful
     2. Surprising without context — a future reader will wonder "why did they do it this way?"
     3. The result of a real trade-off — there were genuine alternatives and you picked one for specific reasons
   • IF: any one of the three is missing → skip the ADR
   • IF: an ADR is warranted and docs/adr/ does not exist → create the directory lazily, scan for the highest existing number, and use the next one
   • Format and numbering: see ./references/ADR-FORMAT.md
   • Example: User decides to use event sourcing for the write model. All three tests pass (hard to reverse, surprising, real trade-off vs. CRUD) → offer to create docs/adr/0003-event-sourced-write-model.md.
   • Example: User decides to name a variable customerId instead of userId. Easy to reverse and not surprising → skip the ADR; this is a glossary concern, not an ADR concern.

References

CONTEXT.md format and rules

• IF: writing or updating a CONTEXT.md entry, deciding what belongs in the glossary vs. an ADR, or working out the structure of a multi-context repo
• THEN: Read ./references/CONTEXT-FORMAT.md
• EXAMPLES:
  • "what does a CONTEXT.md entry look like?"
  • "single context or multi-context — how do I tell?"
  • "should this term go in the glossary?"

ADR format and when to record

• IF: deciding whether a decision deserves an ADR, drafting an ADR, or numbering a new one
• THEN: Read ./references/ADR-FORMAT.md
• EXAMPLES:
  • "is this decision ADR-worthy?"
  • "what sections does an ADR need?"
  • "what number should this ADR be?"

Works well with

Optional collaborators — grill-with-docs runs standalone and these degrade gracefully if absent.

• grill-me — the plain interview without the docs layer; use that when the project has no CONTEXT.md/ADRs to sharpen against.
• setup-toolbox-context — scaffolds the CONTEXT.md and docs/adr/ this skill reads and writes; run it first on a new project.
• living-plan — this skill writes the ADRs; a living plan then links them as back-references and speaks the same CONTEXT.md vocabulary.
• tdd / improve-codebase-architecture — both consume the CONTEXT.md glossary and ADRs this skill produces.