---
name: grill-plan
description: Use when stress-testing a plan against the existing domain model and documented decisions. Challenges terminology, cross-references code, and updates CONTEXT.md and ADRs inline as decisions crystallize.
metadata:
  upstream: mattpocock/skills/engineering/grill-with-docs
  adapted-date: "2026-04-28"
---

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.

## Domain awareness

During codebase exploration, look for existing documentation:

- **`CONTEXT.md`** — glossary of domain terms. If it exists, use its vocabulary in all output. If it doesn't exist, create one when the first term is resolved.
- **`CONTEXT-MAP.md`** — if present at root, the repo has multiple bounded contexts. The map points to where each one lives.
- **`docs/adr/`** — architecture decision records. Create the directory when the first ADR is needed.

## 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? Those are different things."

### Discuss concrete scenarios

When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.

### Cross-reference with code

When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "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. Don't batch these up — capture them as they happen.

Don't couple `CONTEXT.md` to implementation details. Only include terms that are meaningful to domain experts.

### Offer ADRs sparingly

Only offer to create an ADR when all three 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 of the three is missing, skip the ADR.

## ADR format

ADRs live in `docs/adr/` with sequential numbering (`0001-slug.md`). Keep them minimal:

```markdown
# <number>. <Title>

<1-3 sentence context/decision/rationale>
```

Add Status, Considered Options, or Consequences sections only when they add genuine value.