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

## Veille

**Skill**-Eintrag (kein Artikel): `grill-with-docs` von Matt Pocock ist eine strukturierte Interviewtechnik, die einen Architekturplan „grillt“, indem sie ihn methodisch mit dem Fachvokabular des Projekts (dem `CONTEXT.md`-Glossar) und bereits dokumentierten Entscheidungen (ADRs) konfrontiert. Statt vorschnell in die Implementierung zu gehen, hinterfragt sie Annahmen einzeln in einem Frage-Antwort-Dialog, bereinigt die Terminologie, prüft die Konsistenz mit dem tatsächlichen Code und hält Entscheidungen laufend in den passenden Artefakten fest. Ein Upfront-Design-Skill, inspiriert vom 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, Grillen, konfrontatives Interview, Upfront Design, Domain-Driven Design, DDD, Fachvokabular, Glossar, CONTEXT.md, ADR, Architecture Decision Record, Bounded Context, CONTEXT-MAP.md, kanonische Terminologie, Präzision der Sprache, evidenzbasierte Überprüfung, Lazy File Creation, Dokumentationsdisziplin, Terminologie-Drift

## Authors

Matt Pocock

## Ton

Profil: ausführbarer Skill (`SKILL.md`-Anweisungsdatei für einen Agenten), **imperative und sokratisch-konfrontative** Stimme („Interview me relentlessly about every aspect of this plan“), gehobenes technisches Register, Zielgruppe Entwickler und Architekten, die Upfront-Design praktizieren. Hier ist „Ton“ das **operative Register**, das der Skill dem Agenten auferlegt: sequenzielles Befragen (eine Frage nach der anderen, Warten auf die Antwort, bevor es weitergeht), eine Anforderung an lexikalische Präzision (Terminologiekonflikte sofort markieren), eine evidenzbasierte Haltung (Behauptungen mit dem tatsächlichen Code abgleichen und Widersprüche aufdecken) und Dokumentationsdisziplin (laufend festhalten, Dateien bei Bedarf erstellen). Eine durchgehende kulinarische Metapher — *grillen*, den Plan „garen“, um ihn auf die Probe zu stellen. Autorität entsteht aus der Methode (DDD) und der Strenge des Protokolls, nicht aus dem Argument eines Autors.

## Pense-betes

- **Art**: ein **Upfront-Design**-Skill (DDD-geprägt) — vor dem Schreiben von Code wird ein rigoroses Gespräch erzwungen, das ① das Vokabular bereinigt, ② die Konsistenz mit dem bestehenden Code prüft, ③ Entscheidungen am richtigen Ort und auf der richtigen Granularitätsebene dokumentiert.
- **Anti-Drift-Zweck**: **Terminologie-Drift** und **ungeprüfte Annahmen**, die später teuer werden, verhindern.
- **Zwei Zielartefakte**: `CONTEXT.md` (Domänenglossar) und **ADRs** (`docs/adr/`, Architekturentscheidungen).
- **Strenges ADR-Kriterium**: Ein ADR wird nur erstellt, wenn alle **3** Bedingungen zutreffen — die Entscheidung ist (1) schwer umkehrbar, (2) ohne Kontext überraschend, (3) resultiert aus einem **echten Trade-off** mit berücksichtigten Alternativen.
- **`CONTEXT.md` = NUR Fachglossar** — *„sollte völlig frei von Implementierungsdetails sein“* (keine Spezifikationen, keine Entwurfsnotizen).
- **Lazy creation**: *„Dateien nur bei Bedarf erstellen — erst wenn es etwas zu schreiben gibt“* (`CONTEXT.md` beim ersten geklärten Begriff; `docs/adr/` beim ersten benötigten ADR).
- **Multi-Domäne**: Ein Repository mit mehreren *bounded contexts* verwendet eine `CONTEXT-MAP.md`, die auf das `CONTEXT.md` (und `docs/adr/`) jedes Kontexts verweist.
- **Erst erkunden, dann fragen**: Lässt sich eine Frage durch Lesen des Codes klären, erkundet der Agent, statt dich zu fragen — er verschwendet nicht deine Zeit.
- **Warum dies ein Skill-Eintrag und kein Artikel ist**: Der Wert liegt im **wiederverwendbaren Mechanismus** (Trigger, Mechanismus, Artefakte, Anti-Patterns), nicht in einer zeitgebundenen Meinung — siehe den Skill-Block unten.

## RésuméDe400mots

`grill-with-docs`, von Matt Pocock, ist ein **Skill** (ausführbare Anweisungen für einen Coding-Agenten), der die Entwurfsphase in eine rigorose Interviewsitzung verwandelt. Sein Prinzip: Beim Entwurf eines Features ruht der Plan auf Annahmen und Design-Abhängigkeiten; statt vorschnell in die Implementierung zu gehen, „grillt“ der Skill den Plan, indem er ihn Annahme für Annahme mit dem Fachvokabular des Projekts und den bereits getroffenen Entscheidungen konfrontiert. Sobald Entscheidungen sich verfestigen, werden sie in zwei Arten von Dokumenten festgehalten: `CONTEXT.md`, einem **Domänenglossar** (das Fachvokabular), und **ADRs** (*Architecture Decision Records*, in `docs/adr/`), für bedeutsame Architekturentscheidungen.

Der Mechanismus beruht auf vier Prinzipien. **(1) Interviewbasierter Ansatz**: Fragen werden sequenziell gestellt, eine nach der anderen, und der Agent wartet auf die Antwort, bevor er fortfährt; lässt sich eine Frage durch Erkunden des Codes klären, erkundet er ihn, statt zu fragen. **(2) Präzision der Sprache** — der Kern des Skills: Terminologiekonflikte mit dem bestehenden Glossar sofort markieren, einen kanonischen Begriff vorschlagen, wenn der Nutzer ein vages Wort verwendet (z. B. „Account“), und Fachbeziehungen mit konkreten Randfall-Szenarien testen. **(3) Evidenzbasiert**: das angekündigte Verhalten mit dem tatsächlichen Code abgleichen und Widersprüche aufdecken. **(4) Dokumentationsdisziplin**: `CONTEXT.md` wird laufend aktualisiert (nicht gebündelt am Ende); ein ADR wird nur erstellt, wenn die Entscheidung schwer umkehrbar ist, ohne Kontext überraschend wirkt und aus einem echten Trade-off resultiert.

Bei den strukturellen Regeln: `CONTEXT.md` enthält **ausschließlich** das Fachglossar (keine Implementierungsdetails, Spezifikationen oder Entwürfe); ein Repository mit mehreren Domänen (*bounded contexts* im DDD-Sinne) verwendet eine `CONTEXT-MAP.md`, die auf das `CONTEXT.md` jedes Kontexts verweist; Dateien werden **bei Bedarf** erstellt (lazy creation).

Zusammengefasst handelt es sich um einen Upfront-Design-Skill, inspiriert vom Domain-Driven Design, der vor dem Code ein rigoroses Gespräch erzwingt, um ① das Vokabular zu bereinigen, ② die Konsistenz mit dem Bestehenden zu prüfen und ③ Entscheidungen am richtigen Ort und auf der richtigen Granularitätsebene zu dokumentieren — um Terminologie-Drift und ungeprüfte Annahmen zu vermeiden, die später teuer werden.

## 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/de/fiches/skill-pocock-grill-with-docs-2026-06/