La habilidad /grill-with-docs

Fuente: The /grill-with-docs Skill — traducción comunitaria no oficial al español.

Qué hace

grill-with-docs te entrevista sobre un plan o diseño hasta que tú y el agente comparten un entendimiento, y escribe el vocabulario y las decisiones difíciles en tu repo mientras lo hace. Es la misma entrevista que ejecuta grill-me (una ronda de preguntas, luego espera, luego la siguiente ronda), apuntada a una base de código.

Es con estado. Cada otra habilidad de interrogatorio deja la sesión en tu cabeza; esta deja archivos en disco. Un término se resuelve y aterriza en CONTEXT.md en el momento en que se resuelve, no en lote al final. Una decisión pasa tres compuertas y aterriza como ADR. Esa es toda la diferencia, y también es la fuente de la mayoría de los problemas que la gente tiene con la habilidad: los artefactos son archivos reales en un repo real, así que pueden faltar cuando los esperabas, y pueden derivar cuando más de una persona los escribe.

Cuándo usarla

La invocas escribiendo /grill-with-docs; el agente no la usará por su cuenta.

Úsala al inicio de un cambio, en un repo, cuando el plan aún es difuso y las palabras para la cosa aún no están acordadas. Es la herramienta de una sola sesión. Qué habilidad de interrogatorio quieres depende de lo que tienes enfrente:

Lo que tienes	Usa
No estás trabajando en un directorio de trabajo en absoluto	grill-me
Un repo, y un cambio que puedes resolver en una sesión	`grill-with-docs`
Un esfuerzo demasiado grande para caber en una sesión (una construcción greenfield, una funcionalidad grande)	wayfinder
Un repo sin docs de dominio en absoluto, y sin ninguna funcionalidad particular en mente	`grill-with-docs`, apuntada al repo en vez de a un cambio
Una decisión bloqueada por conocimiento en la cabeza de otra persona	to-questionnaire

La división con wayfinder se reduce a conteo de sesiones: /grill-with-docs para planear en una sola sesión, /wayfinder para planear en varias sesiones.

Requisitos previos

La habilidad escribe en tu repo, así que necesitas estar en un lugar donde sea seguro escribir. Los términos resueltos van a un glosario CONTEXT.md en la raíz, o al CONTEXT.md del contexto relevante, si un CONTEXT-MAP.md en la raíz marca el repo como multicontexto. Las decisiones van a docs/adr/. Ambos se crean de forma perezosa; nada existe hasta que el primer término o decisión cristaliza, así que no hay nada que preparar por adelantado.

También necesita otras dos habilidades presentes, porque su propio SKILL.md es una línea que delega en ellas: interrogatorio provee la entrevista, domain-modeling provee la escritura. Instalar grill-with-docs sola te da una habilidad que no funciona.

El rastro documental

Tres cosas salen de una sesión, y no son iguales.

Qué se resolvió	Dónde aterriza
Un término: la propia palabra del proyecto para una cosa	`CONTEXT.md`, inline, en el momento en que se resuelve
Una decisión difícil de revertir, sorprendente sin contexto, y un trade-off real	Un ADR bajo `docs/adr/`
Todo lo demás que decidiste	La conversación, y ningún otro lugar

Esa tercera fila es la que toma a la gente por sorpresa. CONTEXT.md es un glosario y deliberadamente se mantiene como uno: sin detalles de implementación, sin spec, sin notas sueltas. Los ADRs exigen las tres condiciones a la vez, así que la mayoría de las decisiones no califican y la mayoría de las sesiones no produce ninguno. Una sesión que deja un glosario más afilado y cero ADRs funciona como fue diseñada, pero significa que la mayor parte de lo que acordaste existe solo en la ventana de contexto donde lo acordaste. Entrega esa misma conversación a to-spec en vez de limpiarla.

El glosario es el punto. El lenguaje de dominio es lo que esta habilidad realmente está construyendo: las propias palabras del proyecto, acordadas una vez, para que tú, el agente y tus colegas dejen de pagar por rederivarlas. Vale decir que no todos acuerdan que esto te compre rendimiento del agente: la objeción pública más afilada es que un término y su expansión en lenguaje simple obtienen el mismo resultado del modelo, y que el vocabulario realmente comprime la comunicación entre los humanos que lo comparten. Esa lectura igual deja valioso al glosario; solo mueve el valor.

Preguntas frecuentes

¿Debería usar esta o /wayfinder? El alcance lo decide. Usa esta para todo lo que puedas resolver en una sesión; usa wayfinder cuando el esfuerzo sea demasiado grande para caber en una, y traza el trabajo primero como un mapa de tickets de decisión. Wayfinder es más lento y denso, y usarlo en una funcionalidad bien acotada es el error común. No reemplaza a esta habilidad: puede entrar en una sesión de interrogatorio para las partes del mapa que lo admitan.

Corrió, pero no apareció ningún CONTEXT.md ni ADRs. Dos causas conocidas. La mundana: nada calificó. Los ADRs necesitan las tres compuertas, y una sesión sobre un cambio sin vocabulario nuevo genuinamente no tiene nada que escribir. El error real: cuando la habilidad corre dentro de otra capa de orquestación (un envoltorio de desarrollo dirigido por spec, un framework multiagente, una regla que la invoca como paso en el pipeline de otro), se reporta que la mitad de escritura de archivos silenciosamente no ocurre, mientras la entrevista sí corre. Está presentado y sin corregir. Si estás en esa configuración, revisa el directorio de trabajo antes de confiar en la salida de la sesión.

Preguntó todo a la vez, sin recomendaciones, y nunca mencionó CONTEXT.md. Eso es la habilidad fallando en cargar sus dos dependencias. Como SKILL.md es una delegación de una línea, un agente que no recoge interrogatorio y domain-modeling adivina qué significa interrogar, y obtienes un volcado indiferenciado de preguntas. La carga parcial es el caso más confuso: grilling carga, domain-modeling no, y obtienes una buena entrevista sin rastro documental. Correlaciona con modelo y nivel de esfuerzo, y es el problema más reportado de esta habilidad. Si lo sospechas, pregunta al agente directamente qué habilidades cargó.

¿A dónde fueron todas mis demás decisiones? Solo a la conversación. Esta es la queja abierta más sustantiva sobre la habilidad: el glosario no es una spec, la mayoría de las respuestas no ganan un ADR, y no hay un registro que ate cada respuesta resuelta a una spec, un ticket y un test. Las respuestas precisas (garantías de orden, requisitos negativos, valores numéricos por defecto) se suavizan en prosa más débil aguas abajo, y el resultado puede verse completo mientras pierde lo que realmente decidiste. La mitigación disponible hoy es conservar la sesión y alimentarla directo a to-spec, y releer la spec contra tus propias respuestas en vez de suponer que las capturó.

¿Puedo apuntarla a un repo existente que no tiene docs en absoluto? Sí. Esta es la habilidad correcta para una base de código sin ADRs, sin lenguaje de dominio y sin principios de diseño: invócala y di «help me document my repo». El patrón comunitario la combina con improve-codebase-architecture para construir o reparar un CONTEXT.md. Espera dirigirla: leerá código y te preguntará sobre lo que encuentre, y tú eres quien dice cuáles de las palabras que ya están en la base de código son las correctas.

¿Qué debería hacer cuando la sesión termina? El mensaje de cierre de la habilidad tiende a ser abierto, que es una aspereza conocida. En el flujo principal la respuesta es to-spec, en la misma conversación. Si el cambio es lo bastante pequeño para construirse de inmediato, ve directo a implement en cambio.

¿Por qué se llama así? Nadie está contento con el nombre. Hay una sugerencia abierta de renombrarla grill-domain-model, que describe el comportamiento con más honestidad. Nada se ha movido. Si un renombre alguna vez aterriza, la página de docs se mueve con él y la URL cambia.

Funciona si

CONTEXT.md cambia durante la sesión, término por término, en vez de aparecer en un bloque al final.
El glosario se lee como vocabulario puro (las palabras de tu proyecto con definiciones ajustadas) y no contiene detalle de implementación ni prosa tipo spec.
Las preguntas que la base de código puede responder se responden leyendo la base de código, no preguntándote a ti.
Obtienes pocos o ningún ADR, y los que obtienes son decisiones que te molestaría tener que relitigar.
Cuestiona una palabra que usaste porque tu glosario existente la define distinto.

Dónde encaja

grill-with-docs es el inicio de la cadena principal de construcción:

grill-with-docs → to-spec → to-tickets → implement → code-review

Viene antes de que nada se escriba como spec: produce el entendimiento compartido y el vocabulario acordado que to-spec luego sintetiza sin entrevistarte de nuevo. Sus vecinos cercanos son grill-me, la misma entrevista sin repo ni archivos, y domain-modeling, la disciplina de glosario y ADR que dirige; ambas están sobre el primitivo interrogatorio. Aguas arriba, wayfinder traza esfuerzos demasiado grandes para una sesión y puede devolver partes del mapa a esta. Cuando no sabes qué habilidad o flujo encaja, ask-matt te enruta.