# skill-pocock-grill-with-docs-2026-06

## Veille

**Skill** entry (not an article): `grill-with-docs` by Matt Pocock is a structured interview technique that "grills" an architecture plan by methodically confronting it against the project's business vocabulary (the `CONTEXT.md` glossary) and already-documented decisions (ADRs). Rather than rushing into implementation, it challenges assumptions one by one through a question/answer dialogue, cleans up terminology, checks consistency against the actual code, and captures decisions on the fly in the right artifacts. An upfront-design skill, inspired by Domain-Driven Design.

## Titre Article

grill-with-docs — « Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise »

## Date

2026-06-16

## URL

https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/SKILL.md

## Keywords

skill, grilling, adversarial interview, upfront design, Domain-Driven Design, DDD, business vocabulary, glossary, CONTEXT.md, ADR, Architecture Decision Record, bounded context, CONTEXT-MAP.md, canonical terminology, precision of language, evidence-based verification, lazy file creation, documentation discipline, terminology drift

## Authors

Matt Pocock

## Ton

Profile: executable skill (`SKILL.md` instruction file for an agent), **imperative and Socratic-adversarial** voice ("Interview me relentlessly about every aspect of this plan"), elevated technical register, target audience developers and architects practicing upfront design. Here, "tone" is the **operational register** the skill imposes on the agent: sequential questioning (one question at a time, waiting for the answer before moving on), a requirement for lexical precision (immediately flag terminology conflicts), an evidence-based posture (cross-check claims against the actual code and surface contradictions), and documentation restraint (capture on the fly, create files on demand). A sustained culinary metaphor — *grilling*, "cooking" the plan to put it to the test. Authority comes from the method (DDD) and the rigor of the protocol, not from an author's argument.

## Pense-betes

- **Nature**: an **upfront-design** skill (DDD-flavored) — before writing code, force a rigorous conversation that ① cleans up the vocabulary, ② checks consistency with the existing code, ③ documents decisions in the right place and at the right level of granularity.
- **Anti-drift purpose**: prevent **terminology drift** and **unverified assumptions** that become costly later.
- **Two target artifacts**: `CONTEXT.md` (domain glossary) and **ADRs** (`docs/adr/`, architecture decisions).
- **Strict ADR criterion**: an ADR is created only if all **3** conditions hold — the decision (1) is hard to reverse, (2) is surprising without context, (3) stems from a **genuine trade-off** with alternatives considered.
- **`CONTEXT.md` = business glossary ONLY** — *"should be totally devoid of implementation details"* (no specs, no draft notes).
- **Lazy creation**: *"Create files lazily — only when you have something to write"* (`CONTEXT.md` at the first resolved term; `docs/adr/` at the first ADR needed).
- **Multi-domain**: a repo with multiple *bounded contexts* uses a `CONTEXT-MAP.md` that points to the `CONTEXT.md` (and `docs/adr/`) of each context.
- **Explore before asking**: if a question can be settled by reading the code, the agent explores instead of asking you — it doesn't waste your time.
- **Why this is a skill entry and not an article**: the value lies in the **reusable mechanism** (trigger, mechanism, artifacts, anti-patterns), not in a dated opinion — see the Skill block below.

## RésuméDe400mots

`grill-with-docs`, by Matt Pocock, is a **skill** (executable instructions for a coding agent) that turns the design phase into a rigorous interview session. Its principle: when designing a feature, the plan rests on assumptions and design dependencies; rather than rushing into implementation, the skill "grills" the plan by confronting it, assumption by assumption, against the project's business vocabulary and decisions already made. As decisions crystallize, they are captured in two types of documents: `CONTEXT.md`, a **domain glossary** (the business vocabulary), and **ADRs** (*Architecture Decision Records*, in `docs/adr/`), for significant architecture decisions.

The mechanism rests on four principles. **(1) Interview-based approach**: questions are asked sequentially, one at a time, and the agent waits for the answer before moving forward; if a question can be resolved by exploring the code, it explores instead of asking. **(2) Precision of language** — the core of the skill: immediately flag terminology conflicts with the existing glossary, propose a canonical term when the user uses a vague word (e.g. "account"), and test business relationships with concrete edge-case scenarios. **(3) Evidence-based**: cross-check announced behavior against the actual code and surface contradictions. **(4) Documentation discipline**: `CONTEXT.md` is updated on the fly (not in batch at the end); an ADR is created only if the decision is hard to reverse, surprising without context, and stems from a genuine trade-off.

On the structural rules side: `CONTEXT.md` contains **only** the business glossary (no implementation details, specs, or drafts); a repo with multiple domains (*bounded contexts* in the DDD sense) uses a `CONTEXT-MAP.md` that points to each context's `CONTEXT.md`; files are created **on demand** (lazy creation).

In summary, it is an upfront-design skill, inspired by Domain-Driven Design, that forces a rigorous conversation before code to ① clean up the vocabulary, ② check consistency with what already exists, and ③ document decisions in the right place and at the right level of granularity — to avoid terminology drift and unverified assumptions that become costly later.

## Anti-patterns

- **Créer un ADR pour tout** : un ADR n'est justifié que si les **3** critères tiennent simultanément — (1) **difficile à inverser** (coût réel de changer de cap plus tard), (2) **surprenant sans contexte** (un lecteur futur questionnerait la décision), (3) **résultat d'un vrai arbitrage** (des alternatives existaient et ont été pesées). Une décision triviale ou réversible ne devient pas un ADR.
- **Polluer `CONTEXT.md`** avec des détails d'implémentation, des specs ou des notes de brouillon : il doit rester un **glossaire métier pur**.
- **Documenter en lot à la fin** : la capture doit être **inline**, sinon les décisions se perdent.
- **Créer les fichiers en avance** (`CONTEXT.md`/`docs/adr/` vides « au cas où ») : violation de la création paresseuse.
- **Poser des questions dont la réponse est dans le code** : l'agent doit explorer d'abord ; sinon il fait perdre du temps.
- **Foncer dans l'implémentation** sans avoir nettoyé le vocabulaire ni vérifié les hypothèses — c'est précisément ce que la skill cherche à empêcher.

## Artefacts

Structure de repo type :

```
/
├── CONTEXT.md      # glossaire du domaine (vocabulaire métier UNIQUEMENT, zéro détail d'implémentation)
├── docs/adr/       # Architecture Decision Records
└── src/
```

- **`CONTEXT.md`** — glossaire métier ; créé **au premier terme résolu** ; *« totally devoid of implementation details »*.
- **`docs/adr/`** — un fichier par décision d'architecture importante ; créé **au premier ADR nécessaire**.
- **`CONTEXT-MAP.md`** (repos multi-domaines) — pointe vers le `CONTEXT.md` et `docs/adr/` de chaque *bounded context* (DDD).
- **Règle de création** : *« Create files lazily — only when you have something to write. »*

## Commentaire

*Explication pédagogique de la skill (vulgarisation « comment ça marche ») — complément des sections structurées ci-dessous.*

**En une phrase.** C'est une technique d'interview structurée pour « cuisiner » (*grill*) un plan d'architecture : on le met à l'épreuve méthodiquement en le confrontant au vocabulaire métier du projet et aux décisions déjà documentées.

**L'idée centrale.** Quand tu conçois une fonctionnalité, ton plan repose sur des hypothèses et des dépendances de design. Cette skill te fait challenger ces hypothèses **une par une**, via un dialogue question/réponse, plutôt que de foncer dans l'implémentation. À mesure que les décisions se cristallisent, elles sont capturées dans deux types de documents :

- `CONTEXT.md` → un **glossaire du domaine** (le vocabulaire métier) ;
- **ADR** (*Architecture Decision Records*, dans `docs/adr/`) → les **décisions d'architecture** importantes.

**Les 4 principes de fonctionnement.**

1. **Approche par interview** — questions posées séquentiellement, on attend ta réponse avant d'avancer ; si une question peut être résolue en explorant le code, l'agent explore au lieu de demander (il ne te fait pas perdre ton temps).
2. **Précision du langage** (le cœur du truc) — signale immédiatement les conflits de terminologie avec le glossaire existant ; propose un terme canonique quand tu emploies un mot vague ; teste les relations métier avec des scénarios concrets de cas limites (*edge cases*).
3. **Basé sur les preuves** — croise le comportement annoncé avec le code réel ; fait remonter les contradictions entre ce qui est affirmé et ce qui est effectivement implémenté.
4. **Discipline documentaire** — `CONTEXT.md` est mis à jour au fil de l'eau (pas en lot à la fin) ; un ADR n'est créé que si la décision remplit **3 critères** : coût de revirement significatif, justification non évidente qui nécessite du contexte, et vrais arbitrages avec des alternatives considérées.

**Règles structurelles.**

- `CONTEXT.md` = glossaire métier **uniquement** (pas de détails d'implémentation, ni de specs, ni de notes de brouillon).
- Pour un repo avec plusieurs domaines (*bounded contexts* au sens DDD), un `CONTEXT-MAP.md` organise la doc par contexte.
- Les fichiers sont créés **à la demande** : `CONTEXT.md` au premier terme résolu, `docs/adr/` au premier ADR nécessaire.

**En résumé.** C'est essentiellement une skill de **conception en amont** (DDD-flavored) : avant d'écrire du code, on force une conversation rigoureuse qui ① nettoie le vocabulaire, ② vérifie la cohérence avec le code existant, et ③ documente les décisions au bon endroit et au bon niveau de granularité. L'objectif est d'éviter les **dérives de terminologie** et les **hypothèses non vérifiées** qui coûtent cher plus tard.

## Déclencheur

- **Quand l'activer** : lorsqu'on veut **éprouver un plan** (architecture, conception d'une fonctionnalité) contre le langage du projet et ses décisions documentées, *avant* d'implémenter. Texte d'origine : *« Apply this when a user wants to stress-test a plan against their project's language and documented decisions. »*
- **Entrées attendues** : un plan ou une intention de conception à challenger ; l'accès au codebase (la skill explore le code pour répondre aux questions factuelles) ; le cas échéant, un `CONTEXT.md` / `docs/adr/` déjà existants à confronter.
- **Sortie** : un plan durci par le dialogue + des artefacts de documentation (`CONTEXT.md`, ADR) mis à jour au fil de la session.

## Fonctionnement

La skill opère par **questionnement relentless** : *« Interview me relentlessly about every aspect of this plan until we reach a shared understanding. »* Les questions avancent **une à une**, en attendant le retour avant de continuer ; quand c'est possible, l'agent **explore le codebase** plutôt que de poser une question dont la réponse est dans le code.

**Quatre principes de fonctionnement :**

1. **Approche par interview** — séquentielle, interactive ; pas de questions dont la réponse est trouvable dans le code (l'agent va chercher).
2. **Précision du langage** (le cœur) — signaler immédiatement les conflits de terminologie avec le glossaire `CONTEXT.md` (avec exemples précis) ; proposer un **terme canonique** face à un vocabulaire surchargé (ex. « account ») ; éprouver les relations métier via des **scénarios de cas limites** inventés.
3. **Basé sur les preuves** — vérifier les affirmations contre l'implémentation réelle ; faire remonter les contradictions entre ce qui est annoncé et ce qui est effectif.
4. **Discipline documentaire** — mettre à jour `CONTEXT.md` **inline** (au fil de l'eau, pas en lot) ; ne créer un ADR que sous conditions strictes (voir Anti-patterns).

## Lecture commentée du SKILL.md

*Annotation quasi ligne-à-ligne du source : extraits verbatim du `SKILL.md` + glose. Utile pour comprendre comment la skill est construite, pas seulement ce qu'elle fait.*

### Frontmatter

- **`name`** : l'identifiant de la skill. C'est ce que tu taperais (`/grill-with-docs`) pour l'invoquer.
- **`description`** : sert à deux choses — résumer ce que fait la skill **et** indiquer quand l'agent doit la déclencher (« Use when… »). La dernière phrase est la **condition d'activation** : quand tu veux stress-tester un plan contre le langage et les décisions documentées de ton projet.

### Bloc `<what-to-do>` — le cœur comportemental

> *« 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. »*

- **« Interview me relentlessly »** : l'agent doit te questionner sans relâche, pas valider gentiment. Posture **adversariale assumée**.
- **« design tree / one-by-one »** : on traite l'arbre de décisions branche par branche, en résolvant les dépendances entre choix dans l'ordre (un choix peut en contraindre un autre).
- **« provide your recommended answer »** : crucial — à chaque question, l'agent ne se contente pas de demander, il **propose sa propre réponse recommandée**. Ça t'évite la page blanche et donne quelque chose à valider/réfuter.

> *« Ask the questions one at a time, waiting for feedback on each question before continuing. »*

- **Une question à la fois.** Pas de questionnaire massif : un vrai dialogue séquentiel, on attend ta réponse avant la suivante (chaque réponse peut changer les questions suivantes).

> *« If a question can be answered by exploring the codebase, explore the codebase instead. »*

- **Explorer plutôt que demander.** Si la réponse est dans le code, l'agent va la chercher lui-même au lieu de te déranger.

### Bloc `<supporting-info>` — la doc de support

**Domain awareness → structure de fichiers.** Cas standard (un seul contexte) : un `CONTEXT.md` à la racine (le glossaire) + des ADR numérotés dans `docs/adr/` (`0001-…`, `0002-…` — convention ADR classique, séquence chronologique immuable). Si un `CONTEXT-MAP.md` existe à la racine, le repo a **plusieurs contextes** (vocabulaire DDD) : chaque *bounded context* (ex. `src/ordering/`, `src/billing/`) a son propre glossaire et ses propres ADR — car le même mot peut signifier des choses différentes selon le contexte — les ADR globaux restant au niveau racine.

> *« Create files lazily — only when you have something to write. »*

- **Création paresseuse.** Pas de fichiers vides « au cas où » : `CONTEXT.md` naît à la résolution du premier terme, `docs/adr/` au premier ADR réellement nécessaire.

**Challenge against the glossary** — *« Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it? »* → conflit de terminologie = **alerte immédiate** ; c'est le mécanisme anti-dérive du vocabulaire.

**Sharpen fuzzy language** — *« You're saying 'account' — do you mean the Customer or the User? Those are different things. »* → désambiguïsation des termes fourre-tout par un **terme canonique** précis (Customer vs User = deux concepts souvent confondus).

**Discuss concrete scenarios** — *« Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts. »* → test par **cas limites** inventés (« et si on annule une commande déjà à moitié expédiée ? ») qui font sortir les définitions floues au grand jour.

**Cross-reference with code** — *« Your code cancels entire Orders, but you just said partial cancellation is possible — which is right? »* → **confrontation parole vs code**, pilier *evidence-based*.

**Update CONTEXT.md inline** — *« When a term is resolved, update `CONTEXT.md` right there. Don't batch these up. »* (format délégué à `CONTEXT-FORMAT.md`) → documentation **au fil de l'eau**, jamais en lot. Et : *« `CONTEXT.md` should be totally devoid of implementation details. … It is a glossary and nothing else. »* → **frontière stricte** : glossaire pur, pas de specs ni de brouillon.

**Offer ADRs sparingly** — *« Only offer to create an ADR when all three are true: 1. Hard to reverse 2. Surprising without context 3. The result of a real trade-off. If any of the three is missing, skip the ADR. »* (format délégué à `ADR-FORMAT.md`) → les trois conditions sont **cumulatives** ; si une seule manque, pas d'ADR. C'est le garde-fou contre la noyade documentaire.

### Ce qu'il faut retenir sur la **conception** de la skill

Au-delà du contenu, deux choix de design intéressants :

1. **Balises XML sémantiques** (`<what-to-do>`, `<supporting-info>`) — séparent l'**instruction impérative** (le comportement à adopter) de l'**information de référence** (comment faire). Pattern de prompting efficace pour Claude.
2. **Modularisation par fichiers annexes** — les formats détaillés (`CONTEXT-FORMAT.md`, `ADR-FORMAT.md`) sont sortis du `SKILL.md` principal, qui reste un **document d'orchestration concis** ; les détails sont chargés au besoin (progressive disclosure).

## GrapheDeConnaissance

- Matt Pocock —a_créé→ grill-with-docs (METHODOLOGIE, 0.97)
- grill-with-docs —s_applique_à→ éprouver un plan d'architecture avant l'implémentation (CONCEPT, 0.95)
- grill-with-docs —utilise→ interview séquentielle (une question à la fois) (CONCEPT, 0.93)
- grill-with-docs —s_inspire_de→ Domain-Driven Design (METHODOLOGIE, 0.88)
- grill-with-docs —améliore→ précision et cohérence de la terminologie métier (CONCEPT, 0.92)
- grill-with-docs —réduit→ dérives de terminologie et hypothèses non vérifiées (CONCEPT, 0.9)
- grill-with-docs —permet→ CONTEXT.md (DOCUMENT, 0.9)
- grill-with-docs —recommande→ ne créer un ADR que si décision irréversible, surprenante et issue d'un vrai arbitrage (AFFIRMATION, 0.95)
- grill-with-docs —recommande→ Create files lazily — only when you have something to write (CITATION, 0.93)
- grill-with-docs —affirme_que→ CONTEXT.md should be totally devoid of implementation details (CITATION, 0.92)
- CONTEXT.md —est_instance_de→ glossaire du domaine (CONCEPT, 0.92)
- ADR —fait_partie_de→ ADR (CONCEPT, 0.88)
- CONTEXT-MAP.md —référence→ CONTEXT.md (DOCUMENT, 0.87)
- grill-with-docs —s_applique_à→ repos multi-domaines (bounded contexts DDD) (CONCEPT, 0.85)
- grill-with-docs —utilise→ balises XML sémantiques séparant instruction et information de référence (CONCEPT, 0.86)
- grill-with-docs —utilise→ modularisation par fichiers annexes (CONTEXT-FORMAT.md, ADR-FORMAT.md) (CONCEPT, 0.85)

---
Canonical: https://www.thekb.eu/en/fiches/skill-pocock-grill-with-docs-2026-06/