v1.0 to v1.0

---

name: grill-with-docs

Design review session that stress-tests plans against the existing domain model,

sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as

decisions crystallize. Use when validating architecture or plans against a

project's language and documented decisions.

allowed-tools: Read Grep Glob Bash Write Edit

compatibility: >

Works best in codebases with CONTEXT.md and docs/adr/ documentation. Creates

these files lazily if absent. Pairs with improve-codebase-architecture for

architectural work and triage for issue preparation.

metadata:

tags: design-review, architecture, domain-model, documentation, adr, context-map

platforms: Claude, ChatGPT, Gemini, Codex

version: "1.0"

source: mattpocock/skills

---

# Grill With Docs

A grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation inline as decisions crystallize.

## When to use this skill

- Validating architectural plans against a project's domain language

- Stress-testing designs before implementation

- Updating CONTEXT.md terminology as new concepts emerge

- Preparing issues for implementation (pairs with `triage`)

## When not to use this skill

- Finding refactoring opportunities → use `improve-codebase-architecture`

- Writing implementation tickets → use `to-issues`

- General code review → use `code-review`

## Session process

### 1. Explore domain context

Before grilling, read:

- `CONTEXT.md` — existing domain terminology

- `docs/adr/` — prior architectural decisions

- Relevant source files to understand current state

### 2. Run the grilling loop

Interview relentlessly about every decision point. For each question:

- Provide a recommended answer

- Ask one question at a time, waiting for feedback before continuing

- Explore the codebase instead of asking when the answer is findable there

### 3. Three stress-test mechanisms

**Glossary alignment** — When the user uses a term that conflicts with CONTEXT.md, call it out:

> "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"

**Precision sharpening** — When terms are vague or overloaded, propose canonical names:

> "You're saying 'account' — do you mean the Customer or the User? Those are different things."

**Scenario-based edge-case testing** — When domain relationships are discussed, stress-test with concrete scenarios that probe boundaries between concepts.

### 4. Update docs inline

**CONTEXT.md** — When a term is resolved, update it immediately. Don't batch updates.

File structure for single-context repos:

```

/

├── CONTEXT.md

├── docs/

│ └── adr/

│ └── 0001-decision-name.md

```

For monorepos with `CONTEXT-MAP.md` at root, each context has its own `CONTEXT.md` and `docs/adr/`.

Create files lazily — only when you have something to write.

**ADRs** — Only create when all three are true:

1. Hard to reverse (meaningful cost to change later)

2. Surprising without context (future reader would wonder "why?")

3. Result of a real trade-off (genuine alternatives existed)

If any condition is missing, skip the ADR.

## Cross-reference with code

When the user states how something works, verify the code agrees. Surface contradictions:

> "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"

## File formats

- CONTEXT.md: domain terminology meaningful to domain experts (no implementation details)

- ADR format: title, status, context, decision, consequences