grill-with-docs, signée Matt Pocock, est une skill (instructions exécutables pour un agent de codage) qui transforme la phase de conception en une session d'interview rigoureuse. Son principe : quand on conçoit une fonctionnalité, le plan repose sur des hypothèses et des dépendances de design ; plutôt que de foncer dans l'implémentation, la skill « cuisine » (grill) le plan en le confrontant, hypothèse par hypothèse, au vocabulaire métier du projet et aux décisions déjà prises. À 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), et les ADR (Architecture Decision Records, dans docs/adr/), pour les décisions d'architecture importantes.
Le fonctionnement repose sur quatre principes. (1) Approche par interview : les questions sont posées séquentiellement, une à la fois, et l'agent attend la réponse avant d'avancer ; si une question peut être résolue en explorant le code, il explore au lieu de demander. (2) Précision du langage — le cœur de la skill : signaler immédiatement les conflits de terminologie avec le glossaire existant, proposer un terme canonique quand l'utilisateur emploie un mot vague (ex. « account »), et tester les relations métier avec des scénarios concrets de cas limites. (3) Basé sur les preuves : croiser le comportement annoncé avec le code réel et faire remonter les contradictions. (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 est difficile à inverser, surprenante sans contexte, et issue d'un vrai arbitrage.
cuisine
Côté règles structurelles : CONTEXT.md ne contient que le glossaire métier (aucun détail d'implémentation, spec ou brouillon) ; un repo à plusieurs domaines (bounded contexts au sens DDD) utilise un CONTEXT-MAP.md qui pointe vers le CONTEXT.md de chaque contexte ; les fichiers sont créés à la demande (création paresseuse).
En résumé, c'est une skill de conception en amont, d'inspiration Domain-Driven Design, qui force avant le code une conversation rigoureuse pour ① nettoyer le vocabulaire, ② vérifier la cohérence avec l'existant, et ③ documenter les décisions au bon endroit et au bon niveau de granularité — afin d'éviter les dérives de terminologie et les hypothèses non vérifiées qui deviennent coûteuses plus tard.