grill-with-docs: que la IA deje de asentir y te interrogue el plan primero

Resumen en 30 segundos · ¿sin tiempo para todo? quédate con esto

El problema: la IA es demasiado complaciente. Le pasas un plan a medio cocer → escribe código → tu confusión acaba en el proyecto.

grill-with-docs hace lo contrario: te interroga a ti. Usa el glosario de tu CONTEXT.md y el código para sacarle pegas a tu plan, una a una.

Cómo interroga: una pregunta cada vez, con la respuesta recomendada por delante; lee el código en vez de preguntarte cuando puede; un término queda fijado → al CONTEXT.md; una decisión difícil de revertir → un ADR.

Instala: npx skills@latest add mattpocock/skills · Usa: «interrógame el plan con grill-with-docs: »

Ideal para: añadir una función compleja a un proyecto maduro donde unas cuantas palabras significan cosas distintas según quién las diga. Ni te molestes: repo vacío / cambio trivial / esperar que te escriba el código.

1. Una IA complaciente es un pasivo escondido

Lo más peligroso de programar a cuatro manos con una IA es que casi nunca te lleva la contraria.

Le sueltas un plan a medio cocer —«añade una función: que el usuario cancele unos cuantos artículos de un pedido y se le devuelva el dinero»— y ni se inmuta: «¡Claro!», y empieza a brotar el código. Pero esa sola frase está llena de cosas que nunca dejaste claras, y no te preguntó por ninguna: ¿«cancelar» es antes o después del envío? ¿De quién es el reembolso? ¿Es lo mismo que tu código ya llama una cancelación? No pregunta. Lo asume por ti, y deja esas suposiciones incrustadas en el código.

Tres semanas después descubres que esa palabra, «cancelar», significa tres cosas distintas para producto, para tu código y para la base de datos. El código es un amasijo.

No es que la IA no sea lista. Es que quiere ayudar con tantas ganas que no se para a hacerte pensar.

grill-with-docs le da la vuelta: frena a la IA para que no asienta sin más y te interroga el plan primero (en inglés, grill es interrogar a fondo, poner sobre la parrilla). Hasta que las palabras no estén afiladas, no avanzas.

2. Cómo funciona: una entrevista que recuerda tu proyecto

El mecanismo en una línea: usa el lenguaje y las decisiones de tu propio proyecto para interrogar tu plan nuevo.

Unos cuantos detalles (el autor partió este comportamiento en dos skills, grilling y domain-modeling — más abajo):

Una pregunta cada vez, con la respuesta recomendada por delante. Recorre el árbol de decisiones de tu plan rama por rama, y cada pregunta arranca con «yo iría por aquí, porque…» — nada de soltarte un cuestionario de veinte puntos.

Si puede leer el código, no te pregunta. Lo que un vistazo al código resuelve, lo mira él mismo.

Te ata al glosario. Ese CONTEXT.md en la raíz del proyecto es su vara de medir. Suelta una palabra que no cuadre con la definición y te para en seco: «Tu glosario dice que “anular” es X, pero está claro que te refieres a Y — ¿cuál de las dos?».

Las palabras borrosas, las afila. Dices «cuenta» y pregunta: «¿Te refieres al Customer o al User? Son dos cosas distintas».

Contrasta contra el código. Afirmas que una función va de tal manera y lee el código para verificarlo; si no cuadran, lo señala: «El código anula el pedido entero, pero acabas de decir parcial — ¿cuál cuenta?».

Cuando un término queda fijado, va directo al CONTEXT.md. Sin acumular, sin «luego».

Solo una decisión difícil de revertir se gana un ADR. Es tacaño con los ADR (registros de decisión de arquitectura): propone uno únicamente cuando se cumplen las tres condiciones — difícil de revertir, confuso sin contexto, fruto de un compromiso real.

En el fondo son los dos hábitos serios del diseño guiado por el dominio —el lenguaje ubicuo y dejar rastro de las decisiones— metidos dentro de una conversación de la que no te puedes escabullir.

Un cambio que conviene conocer: en realidad son dos skills atornilladas. Matt partió grill-with-docs en grilling (el interrogatorio implacable) y domain-modeling (la disciplina del glosario y los ADR), y dejó grill-with-docs como una carcasa fina cuyo cuerpo es una sola línea: «ejecuta /grilling, usando /domain-modeling». El comportamiento no cambia en nada, pero puedes usar las mitades por separado: ¿solo quieres el interrogatorio? /grilling; ¿solo mantener el glosario y los ADR? /domain-modeling; las dos cosas — eso es grill-with-docs.

3. Manos a la obra: instálalo y pásale un plan

Instala. Está en mattpocock/skills — un comando oficial de una línea; marca grill-with-docs cuando te lo pida:

npx skills@latest add mattpocock/skills

Por ese reparto, grill-with-docs ahora necesita grilling y domain-modeling para estar completo, así que marca las tres (o usa las dos últimas directamente). ¿Ya tienes el repo clonado? Copiar esos directorios al .claude/skills/ de tu proyecto también vale.

Aliméntalo. Deja de decir «impleméntame X». Di esto en su lugar:

Interrógame el plan con grill-with-docs: <suelta aquí ese plan que no has terminado de pensar>

Ojo: lleva la etiqueta disable-model-invocation, así que no aparece por su cuenta — tienes que llamarlo por su nombre (o escribir /grill-with-docs) para arrancarlo. Y luego prepárate: no te va a dar la razón, va a empezar a preguntar.

El primer resultado de verdad suele ser su primera pregunta: algo que creías tener resuelto y, a la primera pregunta, te das cuenta de que no. Esta es una ejecución que hice de verdad.

4. Mira un interrogatorio real

Monté un proyecto pequeño para que lo interrogara, con una trampa puesta a propósito. El proyecto ya tenía un CONTEXT.md:

**Cancellation**:
An order is voided in full before shipping; stock returns to inventory as-is. No refund flow is involved.
_Avoid_: Refund, Return

El código de src/orders.ts también va de frente: cancelOrder() solo anula pedidos enteros, solo antes del envío, nunca toca dinero.

Entonces le pasé el plan (el del principio): «Que el usuario cancele unos cuantos artículos de un pedido (no el pedido entero) y se le devuelva el dinero de esos artículos.»

Leyó el código y el glosario, y su primera línea no fue «Claro» — fue:

Antes de empezar, hay dos conflictos de terminología que señalar.

Tu «cancelar unos artículos y reembolsar» choca con dos definiciones existentes:

CONTEXT.md define Cancellation = anulación del pedido completo + sin flujo de reembolso. Lo que describes es una cancelación parcial, y con reembolso — ambas cosas chocan.

La lista _Avoid_ del glosario excluye expresamente la palabra «Return».

O sea: la acción que describes no tiene palabra existente. Hay que nombrar este concepto nuevo antes de seguir.

No me había dado cuenta para nada: el «cancelar» de mi frase y la Cancellation ya fijada en el proyecto no eran lo mismo. Y no solo lo pilló — fue a leer el código:

El cancelOrder actual, en src/orders.ts:3, solo permite pedidos con status === "PLACED". Tu «cancelar unos artículos» — ¿solo antes del envío, o también después?

Mi recomendación: solo antes del envío. Las devoluciones posteriores al envío son, en términos de negocio, un flujo de devoluciones, un orden de magnitud más complejo… saca primero el camino de antes del envío; el límite queda más limpio.

Respondí «de acuerdo, solo antes del envío». Y entonces hizo algo más importante — nombró el concepto sin nombre y lo escribió directo en el glosario:

Partial Cancellation: antes del envío, se retiran algunos (no todos) los line item de un pedido; el stock de los artículos retirados vuelve al inventario. Sin flujo de reembolso. _Avoid_: Partial refund, Partial return, Item cancellation

Esto lo escribió de verdad en el archivo CONTEXT.md, no solo en el chat. La mitad del reembolso la apartó sin rodeos: «Eso es cosa de Billing — aquí no se escribe».

Avanzando con el interrogatorio hacia los límites, se detuvo a decidir si dejar rastro, y entonces generó de verdad un ADR:

Dejado un ADR en docs/adr/0001-partial-cancellation-no-refund.md: «Partial Cancellation no dispara un reembolso; los reembolsos quedan enteramente en manos del contexto Billing. … La alternativa era disparar el reembolso dentro de Ordering, convirtiendo “cancelar + reembolsar” en una operación atómica — la rechazamos porque haría que Ordering dependiera de las tripas de Billing y rompería el límite de contexto existente.»

Lo mejor es su siguiente pregunta, que citó el mismísimo ADR que acababa de escribir:

Pregunta 3 / ¿Cómo se entera Billing de que hay que reembolsar? El cancelOrder actual no emite ningún evento (src/orders.ts:7).

A. Emitir un evento de dominio; Billing se suscribe y reembolsa.

B. Ordering llama directamente a la API de reembolso de Billing.

C. No emitir nada; que el código que llama lo conecte por su cuenta.

Mi recomendación: A. La opción B hace que Ordering dependa directamente de Billing — justo lo que rechazó el ADR 0001.

Párate a ver el círculo: me hizo afilar una palabra → la escribió en el glosario → registró una decisión de límite como un ADR → y luego usó ese ADR para bloquear una opción posterior que habría roto el límite. Está usando el lenguaje que acabáis de construir juntos para proteger cada paso que viene después. Eso es lo que significa «una entrevista que recuerda tu proyecto».

5. Su carácter: cuándo usarlo y cuándo no forzarlo

Es vigorizante, pero ni es la panacea ni siempre es la jugada correcta:

Necesita algo que interrogar. Con un CONTEXT.md y algo de código, tiene material al que atarte y contra el que contrastar. En un repo vacío y nuevo te construye un glosario desde cero (sigue siendo útil), pero ni de lejos tan afilado como sacar pegas usando el lenguaje que ya tienes. Por eso brilla añadiendo a un proyecto que ya ha crecido.
Afila la claridad, no el código. Un interrogatorio te deja términos afilados, un par de ADR, un plan que de verdad has pensado — no un montón de implementación. Escribir el código es el paso siguiente, cuando ya tienes las ideas claras; no esperes que te lo haga él.
No interrogues lo trivial. El color de un botón, un campo de quita y pon — fuérzalo por el proceso y te seguirá la corriente con toda la seriedad, puro desperdicio. Su valor está donde una palabra borrosa genera líos sin fin: conceptos de dominio, límites de contexto, sitios donde varias ideas se enredan. Un mazo contra una mosca: la mosca tan campante, y tú reventado.
Es tacaño con los ADR — y eso es una virtud, no te fastidies. Registra uno solo cuando se cumplen las tres: difícil de revertir, confuso más adelante, un compromiso real. Cuando te pilles deseando que registrara más, pregúntate: ¿de verdad necesitas el rastro, o solo quieres la ceremonia de tenerlo todo apuntado? Más ADR no es mejor; registrar los que importan, sí.

En una frase: añadir una función compleja a un proyecto maduro, con la mosca detrás de la oreja de que “unas palabras significan cosas distintas según quién las diga” — enciéndelo. Ahí juega en casa.

6. Chuleta

Instalar: npx skills@latest add mattpocock/skills   # marca grill-with-docs en las indicaciones
Interrogar: dile a la IA "interrógame el plan con grill-with-docs: <plan>"

Qué hace:
  una pregunta cada vez, con la respuesta recomendada por delante
  lee el código en vez de preguntarte cuando puede
  te ata al glosario de CONTEXT.md; te para cuando una palabra no cuadra
  afila las palabras borrosas ("cuenta" = Customer o User?)
  contrasta contra el código; señala los desajustes
  término fijado -> escrito directo en CONTEXT.md (glosario, sin detalles de implementación)
  decisión difícil de revertir -> un ADR (docs/adr/, solo si cumple los tres criterios)

CONTEXT.md: solo glosario — una línea o dos por término, la palabra a usar + _Avoid_ las que evitar
Los tres tests del ADR: difícil de revertir + confuso sin contexto + un compromiso real (falla uno, sáltalo)

Ideal para: añadir una función compleja a un proyecto maduro donde "unas palabras significan cosas distintas según quién las diga"
Ni te molestes: repo vacío / cambio trivial / esperar que te escriba el código

7. Para seguir

El código fuente: grill-with-docs (MIT), más las dos en que se partió, grilling y domain-modeling. Las guías de formato del glosario y los ADR ahora viven en domain-modeling: formato de CONTEXT.md, formato de ADR — las dos merecen una lectura.
¿Quieres ir más a fondo? Busca lenguaje ubicuo (ubiquitous language) y ADR (Architecture Decision Record) en el diseño guiado por el dominio (DDD) — grill-with-docs es solo una carcasa ligera que vuelve ambas cosas algo sin esfuerzo.
¿Te gusta esto de «colaborar con la IA desde otro ángulo»? La vez pasada desmenuzamos caveman (hacer que la IA se calle y vaya al grano) — una pareja perfecta: una le quita la paja, la otra le hace plantear las preguntas difíciles. La serie seguirá desmenuzando otras skills del repo de Matt.

Este artículo es contenido educativo original de usesuperpowers.com. La skill grill-with-docs que explica proviene de mattpocock/skills (source_commit: 6eeb81b), bajo su licencia MIT. El interrogatorio que se muestra es una ejecución real (con los detalles accesorios omitidos); las reglas originales citadas son propiedad de su autor; nuestro análisis, nuestra demostración y nuestro texto son originales.

Sobre versiones: este artículo se basa en 6eeb81b. En esta versión Matt partió la antigua grill-with-docs única en dos skills, grilling + domain-modeling, y grill-with-docs pasó a ser el punto de entrada que las combina; el comportamiento descrito y el interrogatorio real de arriba no se ven afectados — solo hay una capa más de «puedes usar las mitades por separado».