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

## Veille

Entrada de tipo **Skill** (no un artículo): `grill-with-docs` de Matt Pocock es una técnica de entrevista estructurada que "somete a la parrilla" un plan de arquitectura confrontándolo metódicamente con el vocabulario de negocio del proyecto (el glosario `CONTEXT.md`) y las decisiones ya documentadas (ADRs). En lugar de precipitarse hacia la implementación, cuestiona las hipótesis una por una mediante un diálogo de preguntas y respuestas, depura la terminología, verifica la coherencia con el código real y registra las decisiones sobre la marcha en los artefactos adecuados. Una skill de diseño previo (upfront design), inspirada en el 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, parrilla, entrevista adversarial, diseño previo, Domain-Driven Design, DDD, vocabulario de negocio, glosario, CONTEXT.md, ADR, Architecture Decision Record, bounded context, CONTEXT-MAP.md, terminología canónica, precisión del lenguaje, verificación basada en evidencia, creación perezosa de archivos, disciplina documental, deriva terminológica

## Authors

Matt Pocock

## Ton

Perfil: skill ejecutable (archivo de instrucciones `SKILL.md` para un agente), voz **imperativa y socrático-adversarial** ("Interview me relentlessly about every aspect of this plan"), registro técnico elevado, dirigida a desarrolladores y arquitectos que practican el diseño previo. Aquí, el "tono" es el **registro operativo** que la skill impone al agente: cuestionamiento secuencial (una pregunta a la vez, esperando la respuesta antes de avanzar), una exigencia de precisión léxica (señalar de inmediato los conflictos de terminología), una postura basada en evidencia (contrastar las afirmaciones con el código real y sacar a la luz las contradicciones), y contención documental (registrar sobre la marcha, crear los archivos bajo demanda). Una metáfora culinaria sostenida — *grilling*, "cocinar" el plan para ponerlo a prueba. La autoridad proviene del método (DDD) y del rigor del protocolo, no del argumento de un autor.

## Pense-betes

- **Naturaleza**: una skill de **diseño previo** (upfront design, con matiz DDD) — antes de escribir código, impone una conversación rigurosa que ① depura el vocabulario, ② verifica la coherencia con el código existente, ③ documenta las decisiones en el lugar adecuado y con el nivel de granularidad correcto.
- **Propósito antideriva**: evitar la **deriva terminológica** y las **hipótesis no verificadas** que resultan costosas más adelante.
- **Dos artefactos objetivo**: `CONTEXT.md` (glosario de dominio) y las **ADR** (`docs/adr/`, decisiones de arquitectura).
- **Criterio estricto para las ADR**: una ADR se crea solo si se cumplen las **3** condiciones — la decisión (1) es difícil de revertir, (2) es sorprendente sin contexto, (3) procede de un **verdadero trade-off** con alternativas consideradas.
- **`CONTEXT.md` = glosario de negocio ÚNICAMENTE** — *"debe estar totalmente desprovisto de detalles de implementación"* (sin especificaciones, sin notas de borrador).
- **Creación perezosa**: *"Crear los archivos de forma perezosa — solo cuando hay algo que escribir"* (`CONTEXT.md` en el primer término resuelto; `docs/adr/` en la primera ADR necesaria).
- **Multidominio**: un repositorio con múltiples *bounded contexts* utiliza un `CONTEXT-MAP.md` que remite al `CONTEXT.md` (y a `docs/adr/`) de cada contexto.
- **Explorar antes de preguntar**: si una pregunta puede resolverse leyendo el código, el agente explora en lugar de preguntarte — no hace perder tiempo.
- **Por qué es una entrada de tipo skill y no un artículo**: el valor reside en el **mecanismo reutilizable** (disparador, mecanismo, artefactos, antipatrones), no en una opinión fechada — véase el bloque Skill más abajo.

## RésuméDe400mots

`grill-with-docs`, de Matt Pocock, es una **skill** (instrucciones ejecutables para un agente de codificación) que convierte la fase de diseño en una rigurosa sesión de entrevista. Su principio: al diseñar una funcionalidad, el plan se apoya en hipótesis y dependencias de diseño; en lugar de precipitarse hacia la implementación, la skill "somete a la parrilla" el plan confrontándolo, hipótesis por hipótesis, con el vocabulario de negocio del proyecto y las decisiones ya tomadas. A medida que las decisiones se cristalizan, se registran en dos tipos de documentos: `CONTEXT.md`, un **glosario de dominio** (el vocabulario de negocio), y las **ADR** (*Architecture Decision Records*, en `docs/adr/`), para las decisiones de arquitectura significativas.

El mecanismo se apoya en cuatro principios. **(1) Enfoque basado en entrevista**: las preguntas se plantean secuencialmente, una a la vez, y el agente espera la respuesta antes de avanzar; si una pregunta puede resolverse explorando el código, el agente explora en lugar de preguntar. **(2) Precisión del lenguaje** — el núcleo de la skill: señalar de inmediato los conflictos de terminología con el glosario existente, proponer un término canónico cuando el usuario emplea una palabra vaga (por ejemplo, "cuenta"), y poner a prueba las relaciones de negocio con escenarios de casos límite concretos. **(3) Basado en evidencia**: contrastar el comportamiento anunciado con el código real y sacar a la luz las contradicciones. **(4) Disciplina documental**: `CONTEXT.md` se actualiza sobre la marcha (no en bloque al final); una ADR se crea solo si la decisión es difícil de revertir, sorprendente sin contexto, y procede de un verdadero trade-off.

En cuanto a las reglas estructurales: `CONTEXT.md` contiene **únicamente** el glosario de negocio (sin detalles de implementación, especificaciones ni borradores); un repositorio con múltiples dominios (*bounded contexts* en el sentido DDD) utiliza un `CONTEXT-MAP.md` que remite al `CONTEXT.md` de cada contexto; los archivos se crean **bajo demanda** (creación perezosa).

En resumen, se trata de una skill de diseño previo, inspirada en el Domain-Driven Design, que impone una conversación rigurosa antes de escribir código para ① depurar el vocabulario, ② verificar la coherencia con lo ya existente y ③ documentar las decisiones en el lugar adecuado y con el nivel de granularidad correcto — para evitar la deriva terminológica y las hipótesis no verificadas que resultan costosas más adelante.

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