---
name: grill-with-docs
description: >
  Domain-driven grilling session that challenges a plan against
  the project's language, sharpens terminology, and writes
  documentation inline as decisions crystallise. Use when the
  user wants to stress-test a plan against domain language, says
  "grill with docs", "sharpen terms", "challenge against domain",
  or wants a grilling session that produces glossary updates and
  ADRs as it goes.
metadata:
  version: "1.0.0"
  tags: "category:review, category:architecture, category:documentation"
---

# Grill With Docs

Interview the user relentlessly about their plan while
maintaining domain documentation inline. Walk down each
branch of the design tree, resolving dependencies between
decisions one by one.

## Workflow

1. **Read the artifact** — Read the plan, spec, or design.
   Understand the full scope before asking anything.

2. **Explore the codebase** — Before asking questions, look
   for existing documentation:
   - `docs/context/GLOSSARY.md` — domain language
   - `docs/context/CODEBASE.md` — context boundaries
   - `docs/adr/` — existing architectural decisions
   - Code patterns related to the plan's domain

3. **Interview one question at a time** — Ask exactly ONE
   question per message. Never combine multiple questions
   in a single response, even if they seem related. For
   each question, state YOUR recommended answer first.
   Wait for the user's response before asking the next
   question. If a question can be answered by exploring
   the codebase, explore instead of asking.

4. **Challenge against the glossary** — When the user uses
   a term that conflicts with `GLOSSARY.md`, call it out:
   "Your glossary defines 'X' as Y, but you seem to mean
   Z — which is it?"

5. **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?"

6. **Discuss concrete scenarios** — Stress-test domain
   relationships with specific scenarios that probe edge
   cases and force precision about boundaries.

7. **Cross-reference with code** — When the user states how
   something works, check whether the code agrees. Surface
   contradictions: "Your code does X, but you just said
   Y — which is right?"

8. **Update GLOSSARY.md inline** — When a term is resolved,
   update `docs/context/GLOSSARY.md` immediately. Do not
   batch. Create the file lazily if it doesn't exist. See
   [glossary-format.md](references/glossary-format.md).

9. **Update CODEBASE.md if needed** — When context
   boundaries or relationships are clarified, update
   `docs/context/CODEBASE.md`. Create lazily. See
   [codebase-format.md](references/codebase-format.md).

10. **Offer ADRs sparingly** — Only when all three criteria
    in [adr-criteria.md](references/adr-criteria.md) are
    met. When warranted, explicitly state "Delegating to
    create-adr" and activate the `create-adr` skill to
    handle format, numbering, and file placement. Do not
    write ADR files directly.

11. **Continue until covered** — Keep going until all
    branches are resolved. Do not stop early.

12. **Summarize and offer to apply** — Summarize decisions
    made, then ask: "Want me to apply these changes to
    [artifact name]?"

## Boundaries

**DOES:**
- Interview relentlessly about a plan or design
- Update GLOSSARY.md inline as terms are resolved
- Update CODEBASE.md when boundaries are clarified
- Delegate to create-adr when ADR criteria are met
- Cross-reference claims against code

**Does NOT:**
- Implement code changes
- Create ADRs directly (delegates to create-adr)
- Replace grill-me for quick artifact reviews
- Modify files without resolving terms first

## Common Failures

- **Batching glossary updates** — write terms as they're
  resolved, not at the end. Users forget context.
- **Creating ADRs too eagerly** — most decisions don't
  need one. Apply the three-gate test strictly.
- **Accepting vague terms** — "the service handles it"
  is not precise. Push until the term has a one-sentence
  definition and an _Avoid_ list.
- **Bundling multiple questions** — NEVER ask two questions
  in one message. If you have a follow-up, wait for the
  answer first. One message = one question. Always.
- **Writing ADRs directly** — When an ADR is warranted,
  you MUST say "Delegating to create-adr" and hand off.
  Do not write the ADR file yourself. The create-adr skill
  owns the format, numbering, and lifecycle.

# ADR Criteria

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 is missing, skip the ADR.

## What qualifies

- Architectural shape (monorepo, event sourcing, etc.)
- Integration patterns between contexts
- Technology choices that carry lock-in (database, auth
  provider, deployment target)
- Boundary and scope decisions (who owns what data)
- Deliberate deviations from the obvious path
- Constraints not visible in code (compliance, SLAs)
- Rejected alternatives when rejection is non-obvious

## What does NOT qualify

- Easy to reverse — just reverse it when needed
- Not surprising — nobody will wonder why
- No real alternative — "we did the obvious thing"
- Library choices (unless lock-in is significant)
- General best practices everyone follows

## When criteria are met

Delegate to the `create-adr` skill. Do not duplicate its
workflow — just pass the decision context and let it handle
the format, numbering, and file placement.

# Codebase

## Contexts

- [Ordering](./src/ordering/) — receives and tracks
  customer orders
- [Billing](./src/billing/) — generates invoices and
  processes payments
- [Fulfillment](./src/fulfillment/) — manages warehouse
  picking and shipping

## Relationships

- **Ordering → Fulfillment**: Ordering emits `OrderPlaced`
  events; Fulfillment consumes them to start picking
- **Fulfillment → Billing**: Fulfillment emits
  `ShipmentDispatched`; Billing generates invoices
- **Ordering ↔ Billing**: Shared types for `CustomerId`
  and `Money`

# CODEBASE.md Format

Location: `docs/context/CODEBASE.md`

## Purpose

Maps the project's contexts, where they live, and how
they relate. The "you are here" file for the repo.

## Structure

```md
# Codebase

## Contexts

- [Ordering](./src/ordering/) — receives and tracks
  customer orders
- [Billing](./src/billing/) — generates invoices and
  processes payments
- [Fulfillment](./src/fulfillment/) — manages warehouse
  picking and shipping

## Relationships

- **Ordering → Fulfillment**: Ordering emits `OrderPlaced`
  events; Fulfillment consumes them to start picking
- **Fulfillment → Billing**: Fulfillment emits
  `ShipmentDispatched`; Billing generates invoices
- **Ordering ↔ Billing**: Shared types for `CustomerId`
  and `Money`
```

## Rules

- List each context with its directory and a one-line
  purpose
- Relationships show direction and mechanism (events,
  shared types, API calls)
- Keep it structural — no implementation details
- Update when new contexts emerge or relationships change

## When to create

Create lazily when a grilling session reveals multiple
bounded contexts in the codebase. Single-context projects
don't need this file.

# Glossary

{One sentence: what domain this glossary covers.}

## Language

**Order**:
A customer's request to purchase one or more items.
_Avoid_: Purchase, transaction

**Invoice**:
A request for payment sent to a customer after delivery.
_Avoid_: Bill, payment request

**Customer**:
A person or organization that places orders.
_Avoid_: Client, buyer, account

# GLOSSARY.md Format

Location: `docs/context/GLOSSARY.md`

## Structure

```md
# Glossary

{One sentence: what domain this glossary covers.}

## Language

**Order**:
A customer's request to purchase one or more items.
_Avoid_: Purchase, transaction

**Invoice**:
A request for payment sent to a customer after delivery.
_Avoid_: Bill, payment request

**Customer**:
A person or organization that places orders.
_Avoid_: Client, buyer, account
```

## Rules

- **Be opinionated.** When multiple words exist for the same
  concept, pick one and list others under `_Avoid_`.
- **Keep definitions tight.** One or two sentences. Define
  what it IS, not what it does.
- **Only domain-specific terms.** General programming concepts
  don't belong. Ask: is this unique to this project's domain?
- **Group under subheadings** when natural clusters emerge.
  Flat list is fine when all terms belong to one area.

## When to create

Create `docs/context/GLOSSARY.md` lazily — only when the
first term is resolved during a grilling session.

## When to update

Update inline during the session, not batched at the end.
When a term is sharpened or resolved, write it immediately.