mp-grill-with-docs

---
name: mp-grill-with-docs
description: "Use when you want a relentless grilling session that stress-tests a plan against the project's domain glossary (CONTEXT.md) and prior ADRs, sharpening terminology and updating docs inline as decisions crystallise."
source: https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/SKILL.md
generated: 2026-05-12T18:05:05.376Z
category: concept
audience: engineers
---

## Tutorials

- https://skillmake.xyz/v/mp-grill-with-docs.mp4

## When to use

- Stress-testing a feature plan against the project's existing domain language before writing code
- Vague or overloaded terms ('account', 'cancellation') are being thrown around and need to be pinned down
- A hard-to-reverse, surprising decision is about to be made and may warrant an ADR
- Onboarding to an unfamiliar repo and you want to build a shared mental model with the maintainer

## Key concepts

### one question at a time

Walk down each branch of the design tree, resolving dependencies one decision at a time. For each question, provide your recommended answer, then wait for feedback before moving on. Don't batch questions — one-at-a-time keeps the conversation grippy.

### explore the codebase instead of asking

If a question can be answered by reading the code, do that instead of asking. Cross-reference the user's claims against actual implementation — if they contradict, surface the contradiction: 'Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?'

### CONTEXT.md (single or multi-context)

Most repos have a single domain glossary at /CONTEXT.md. If /CONTEXT-MAP.md exists, the repo has multiple bounded contexts mapped to subdirs (e.g. src/ordering/CONTEXT.md, src/billing/CONTEXT.md), with system-wide ADRs at /docs/adr/ and context-specific ones nested. Create files lazily — only when there's a term or decision worth writing.

### challenge against the glossary

When the user uses a term that conflicts with CONTEXT.md, call it out immediately. 'Your glossary defines cancellation as X, but you seem to mean Y — which is it?' Sharpen fuzzy/overloaded terms by proposing a precise canonical name — 'account' usually splits into 'Customer' vs 'User'.

### concrete scenarios as probes

When relationships between concepts are being discussed, invent specific scenarios that probe edge cases and force the user to be precise about boundaries. Abstract relationships hide ambiguity; concrete scenarios surface it.

### update CONTEXT.md inline

When a term is resolved, update CONTEXT.md right there — don't batch up changes. Capture decisions as they happen. Don't couple CONTEXT.md to implementation details; only include terms meaningful to domain experts.

### ADRs only when all three are true

Offer to create an ADR only when the decision is (1) hard to reverse, (2) surprising without context — a future reader will wonder 'why did they do it this way?', and (3) the result of a real trade-off with genuine alternatives. If any one is missing, skip the ADR. Use the format in the repo's ADR-FORMAT.md.

## API reference

```
Repo layout — single context
```

The common case. One CONTEXT.md at the root, ADRs in docs/adr/. No CONTEXT-MAP.md needed.

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

```
Repo layout — multiple contexts (CONTEXT-MAP.md at root)
```

When the repo has multiple bounded contexts, each lives in its own subdirectory with a local CONTEXT.md and docs/adr/. System-wide ADRs stay at the top.

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

## Gotchas

- Ask ONE question at a time. Batching kills the grilling rhythm and lets the user dodge specifics.
- If a question can be answered by reading the code, read the code — don't ask.
- Create CONTEXT.md and docs/adr/ lazily. Don't scaffold them upfront — only when there's a real term or decision to write.
- Don't couple CONTEXT.md to implementation details. Only include terms meaningful to domain experts.
- Only offer an ADR when all three are true: hard to reverse, surprising without context, and a real trade-off. Otherwise skip.
- Update CONTEXT.md inline as terms resolve — don't batch the updates, you'll forget the precise wording.
- When the user's words contradict the code, surface it immediately rather than picking one and moving on.
- Stress-test domain relationships with concrete scenarios, not abstract phrasing — ambiguity hides in the abstract.

---
Generated by SkillMake from https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/SKILL.md on 2026-05-12T18:05:05.376Z.
Verify against source before relying on details.

File: ~/.claude/skills/mp-grill-with-docs/SKILL.md