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.