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

## Veille

Voce di tipo **Skill** (non un articolo): `grill-with-docs` di Matt Pocock è una tecnica di intervista strutturata che "mette alla griglia" un piano di architettura confrontandolo metodicamente con il vocabolario di business del progetto (il glossario `CONTEXT.md`) e con le decisioni già documentate (gli ADR). Invece di precipitarsi nell'implementazione, mette in discussione le ipotesi una per una attraverso un dialogo domanda/risposta, ripulisce la terminologia, verifica la coerenza rispetto al codice effettivo e cattura le decisioni al volo negli artefatti giusti. Una skill di design a monte (upfront-design), ispirata al 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, grigliata, intervista avversariale, design a monte, Domain-Driven Design, DDD, vocabolario di business, glossario, CONTEXT.md, ADR, Architecture Decision Record, bounded context, CONTEXT-MAP.md, terminologia canonica, precisione del linguaggio, verifica basata sull'evidenza, creazione lazy dei file, disciplina documentale, deriva terminologica

## Authors

Matt Pocock

## Ton

Profilo: skill eseguibile (file di istruzioni `SKILL.md` per un agente), voce **imperativa e socratico-avversariale** ("Interrogami senza sosta su ogni aspetto di questo piano"), registro tecnico elevato, pubblico target sviluppatori e architetti che praticano il design a monte. Qui, il "tono" è il **registro operativo** che la skill impone all'agente: interrogazione sequenziale (una domanda alla volta, attesa della risposta prima di procedere), un requisito di precisione lessicale (segnalare immediatamente i conflitti terminologici), una postura basata sull'evidenza (verificare le affermazioni incrociandole con il codice effettivo e far emergere le contraddizioni), e una moderazione documentale (catturare al volo, creare i file su richiesta). Una metafora culinaria sostenuta — *grigliare*, "cuocere" il piano per metterlo alla prova. L'autorità deriva dal metodo (DDD) e dal rigore del protocollo, non dall'argomentazione di un autore.

## Pense-betes

- **Natura**: una skill di **design a monte** (upfront-design, in stile DDD) — prima di scrivere codice, impone una conversazione rigorosa che ① ripulisce il vocabolario, ② verifica la coerenza con il codice esistente, ③ documenta le decisioni nel posto giusto e al giusto livello di granularità.
- **Finalità anti-deriva**: prevenire la **deriva terminologica** e le **ipotesi non verificate** che diventano costose in seguito.
- **Due artefatti target**: `CONTEXT.md` (glossario di dominio) e gli **ADR** (`docs/adr/`, decisioni di architettura).
- **Criterio rigido per l'ADR**: un ADR viene creato solo se tutte e **3** le condizioni sono soddisfatte — la decisione (1) è difficile da invertire, (2) è sorprendente senza contesto, (3) deriva da un **compromesso reale** (trade-off) con alternative considerate.
- **`CONTEXT.md` = SOLO glossario di business** — *"deve essere totalmente privo di dettagli implementativi"* (niente specifiche, niente appunti di bozza).
- **Creazione lazy**: *"Crea i file in modo lazy — solo quando hai qualcosa da scrivere"* (`CONTEXT.md` al primo termine risolto; `docs/adr/` al primo ADR necessario).
- **Multi-dominio**: un repository con più *bounded context* usa un `CONTEXT-MAP.md` che punta al `CONTEXT.md` (e a `docs/adr/`) di ciascun contesto.
- **Esplorare prima di chiedere**: se una domanda può essere risolta leggendo il codice, l'agente esplora invece di chiedere all'utente — non fa perdere tempo.
- **Perché è una voce di tipo skill e non un articolo**: il valore risiede nel **meccanismo riutilizzabile** (trigger, meccanismo, artefatti, anti-pattern), non in un'opinione datata — vedi il blocco Skill qui sotto.

## RésuméDe400mots

`grill-with-docs`, di Matt Pocock, è una **skill** (istruzioni eseguibili per un agente di codifica) che trasforma la fase di design in una rigorosa sessione di intervista. Il suo principio: quando si progetta una funzionalità, il piano poggia su ipotesi e dipendenze di design; invece di precipitarsi nell'implementazione, la skill "mette alla griglia" il piano confrontandolo, ipotesi per ipotesi, con il vocabolario di business del progetto e con le decisioni già prese. Man mano che le decisioni si cristallizzano, vengono catturate in due tipi di documenti: `CONTEXT.md`, un **glossario di dominio** (il vocabolario di business), e gli **ADR** (*Architecture Decision Records*, in `docs/adr/`), per le decisioni di architettura significative.

Il meccanismo si basa su quattro principi. **(1) Approccio basato sull'intervista**: le domande vengono poste in sequenza, una alla volta, e l'agente attende la risposta prima di procedere; se una domanda può essere risolta esplorando il codice, l'agente esplora invece di chiedere. **(2) Precisione del linguaggio** — il cuore della skill: segnalare immediatamente i conflitti terminologici con il glossario esistente, proporre un termine canonico quando l'utente usa una parola vaga (ad es. "account"), e testare le relazioni di business con scenari concreti di casi limite. **(3) Basato sull'evidenza (evidence-based)**: verificare incrociando il comportamento dichiarato con il codice effettivo e far emergere le contraddizioni. **(4) Disciplina documentale**: `CONTEXT.md` viene aggiornato al volo (non in blocco alla fine); un ADR viene creato solo se la decisione è difficile da invertire, sorprendente senza contesto, e deriva da un compromesso (trade-off) reale.

Sul fronte delle regole strutturali: `CONTEXT.md` contiene **solo** il glossario di business (nessun dettaglio implementativo, nessuna specifica, nessuna bozza); un repository con più domini (*bounded context* nel senso DDD) usa un `CONTEXT-MAP.md` che punta al `CONTEXT.md` di ciascun contesto; i file vengono creati **su richiesta** (creazione lazy).

In sintesi, è una skill di design a monte, ispirata al Domain-Driven Design, che impone una conversazione rigorosa prima del codice per ① ripulire il vocabolario, ② verificare la coerenza con ciò che già esiste, e ③ documentare le decisioni nel posto giusto e al giusto livello di granularità — per evitare la deriva terminologica e le ipotesi non verificate che diventano costose in seguito.

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