🔍 Qué es el grilling
Grilling es una sesión en la que el el agente pregunta detalles antes de programar. No eres tú quien enumera los requisitos. Es el agente, en el papel de entrevistador adversarial, quien te lleva a áreas en las que aún no habías pensado: casos límite, decisiones que estás postergando, premisas que ni siquiera sabías que estabas suponiendo.
La mayoría de las personas usa los LLM como un autocompletado glorificado: dan un prompt vago y aceptan el primer código. El resultado: 3 rondas de retrabajo. Grilling invierte esto. El agente se convierte en el pesado que pregunta "¿y si el usuario no tiene conexión?", "¿cómo quieres manejar los duplicados?", "¿es por tenant o global?", antes de que salga una sola línea.
🎯 El principio central
El código de mala calidad no se debe a un modelo débil. Se debe a brief débil. El interrogatorio obliga a que el brief quede bien antes de gastar tokens en la implementación.
- • El agente no supone: pregunta.
- • No escribes una spec: respondes.
- • La alineación queda por escrito, no solo en tu cabeza.
💡 Por qué la inversión lo cambia todo
Cuándo tú escribe la spec; tú solo enumeras lo que ya pensaste. Cuando el agente pregunta, explora el espacio de decisiones que todavía no has visto. El agente leyó mil sistemas parecidos: sabe dónde está el bug.
La pregunta del agente es el mapa de lo que todavía no sabías que tenías que decidir.
Conceptos clave
⚖️ /grill-me vs /grill-with-docs
Hay dos variantes. Elegir mal no rompe nada; solo desperdicia contexto. El /grill-me es ligero, conversacional, ideal para decisiones que no implican código. El /grill-with-docs es pesado, lee tu CONTEXT.md y tus ADRs, y los actualiza al final.
✓ /grill-me
- ✓Decisiones de producto sin mucho código
- ✓Lluvia de ideas sobre una feature antes del PRD
- ✓No técnico: copy, posicionamiento, flujo
- ✓Output: bullets de decisión en la conversación
- ✓No modifica archivos del proyecto
✓ /grill-with-docs
- ✓Ingeniería: feature, refactor, decisión técnica
- ✓Lee CONTEXT.md, los ADRs y el modelo de dominio
- ✓Actualiza CONTEXT.md y crea un ADR al final
- ✓Output: documentos persistentes
- ✓Usa la terminología del proyecto, no una genérica
Comparación directa
| Aspecto | /grill-me | /grill-with-docs |
|---|---|---|
| Input | Idea suelta | Idea + proyecto indexado |
| ¿Lee archivos? | No | Sí — CONTEXT.md, ADRs, código |
| ¿Escribe archivos? | No | Sí — actualiza CONTEXT.md, crea un ADR |
| Duración típica | 5–10 min | 15–40 min |
| Siguiente paso | Documentar manualmente | /to-prd directamente |
📊 Regla práctica
Si la decisión se convertirá en código — /grill-with-docs. Si la decisión se queda solo en tu cabeza — /grill-me. En caso de duda, elige /grill-with-docs: el costo de generar un ADR más es cero; el costo de perder contexto es alto.
Conceptos clave
🎯 Cuándo usar (y cuándo NO usar)
Grilling no es gratis: cuesta de 10 a 40 minutos. Para cambios triviales, ese costo supera el retrabajo que evita. Para decisiones arquitectónicas, es la inversión más barata que existe.
✓ USAR grilling
- ✓Nueva funcionalidad — primer contacto con el problema
- ✓Decisión arquitectónica — elección de base de datos, cola, patrón
- ✓Bug confuso — ni siquiera sabes cómo reproducirlo
- ✓Refactor — antes de tocar 20 archivos
- ✓Integración — tercero, webhook, contratos
- ✓Migración — schema, framework, versión
✗ SALTARSE grilling
- ✗Error tipográfico / arreglo trivial — una línea, alcance claro
- ✗Cambio de copy — texto ya aprobado
- ✗Actualización de versión — sin breaking changes
- ✗Patrón ya documentado — sigue el ADR existente
- ✗Bug con causa obvia — stack trace claro
- ✗Sesión de programación en pareja — alineación humana ya hecha
⚠️ Cuidado con «parece trivial»
"Solo agregar un campo al formulario" terminó convirtiéndose en un refactor de validación, una migración de base de datos y un cambio de API en tres proyectos diferentes. Cuando escuches "es solo una cosita" y el asunto toca la persistencia o el contrato, dedica 10 min al grill. Descubrirás que no es tan "solo" así.
Conceptos clave
💬 Ejemplo de una sesión completa
Diálogo realista de /grill-with-docs sobre una feature común: «quiero agregar autenticación». Observa cómo cada pregunta del agente cierra una decisión que se convertiría en un bug si quedara implícita.
• Modelo: B2B multi-tenant, una sola DB con tenant_id
• Onboarding: El admin invita por email, sin registro libre
• Auth: Magic link (fase 1), SSO (fase 2). Un solo email por tenant
• Roles: owner > admin > member; owner exclusivo para billing
• Sesión: cookie httpOnly server-side, 7d, revocación global soportada
• Lifecycle: no puede salir el último owner; soft delete predeterminado
¿Listo para /to-prd?
💡 Observación importante
Observa que NINGUNA de estas 6 preguntas estaba en el prompt original «quiero agregar autenticación». Cada respuesta cerró una decisión que habría terminado en una reunión de 2 h o en un bug en producción. Ese es el ROI del grilling.
Conceptos clave
🚫 Antipatrones de grilling
Grilling es simple, pero tiene trampas. El síntoma habitual: terminaste el grill, pero sigues sintiendo que habrá retrabajo. Casi siempre se debe a uno de los tres antipatrones de abajo.
✓ Enfoque saludable
- ✓Refuta el primer borrador del agente si te parece vago
- ✓Pide que reformule las preguntas genéricas
- ✓Trata un cambio "pequeño" que escala como una feature
- ✓Para el grill cuando notes que el problema cambió
- ✓Responde "no sé" cuando sea cierto, e investiga antes de concluir
✗ Antipatrones
- ✗Aceptar el primer borrador sin interrogar — «está bien así»
- ✗Tragarse preguntas vagas como "¿cómo quieres hacer esto?"
- ✗Omitir el grilling en un cambio «trivial» que afecta el contrato
- ✗Responder "depende" para evadir la decisión
- ✗No revisar el ADR final: firmar sin leer
🚨 Una pregunta vaga es una señal de alerta
Si el agente pregunta "¿cómo quieres estructurar esto?" — detente. Esa no es una pregunta de grill; es el agente devolviéndote la decisión. Exige especificidad:
Respuesta correcta: "Dame 3 opciones con sus tradeoffs y pregúntame qué criterio es importante para que yo elija."
Conceptos clave
🔗 Integración con PRD
Grilling no es un evento aislado: es la primera etapa de un pipeline. Las decisiones se convierten en contexto, el contexto en PRD, el PRD en issues y las issues en código. Todo está encadenado.
/grill-with-docs
Entrada: idea suelta. Salida: decisiones cerradas.
El agente lee CONTEXT.md, hace 5–10 preguntas específicas y sintetiza las respuestas en decisiones con nombre.
CONTEXT.md actualizado
Las decisiones se convierten en texto permanente.
Las respuestas del grill se guardan en CONTEXT.md (y, cuando son arquitectónicas, en un ADR numerado en docs/adr/).
/to-prd usa el contexto
El PRD nace alineado, no de la imaginación del LLM.
El comando /to-prd lee CONTEXT.md + ADRs recientes y genera un PRD que cita las decisiones. Sin grilling, el PRD se vuelve ficción.
/to-issues divide en partes verticales
El PRD se convierte en tareas ejecutables de principio a fin.
Cada issue es un vertical slice: UI + API + persistencia + prueba. No se organiza horizontalmente por capa. Las issues heredan la terminología del CONTEXT.md.
Implementación
El código se genera con un brief sólido.
Cuando el agente vaya a programar el issue, tendrá el ADR + PRD + issue. El retrabajo se reduce un 60–80 % en comparación con partir de un prompt vago.
📊 El encadenamiento es el producto
Grilling por sí solo genera un documento. El pipeline grill → ADR → PRD → issues genera previsibilidad. Es la diferencia entre «uso IA» y «tengo un proceso con IA».
Conceptos clave
🛠️ Ejercicio práctico
Toma una feature que quieras construir hoy — no dentro de dos semanas. Ejecuta /grill-with-docs y responde con honestidad. No hagas trampa acelerando el grill.
Quiero agregar [tu feature en una frase] al proyecto.
Haz grilling antes de que escriba el PRD. Quiero preguntas específicas, justificando por qué cada una cambia la implementación. Una pregunta a la vez. Si doy una respuesta vaga, refútala y vuelve a preguntar. Al final, sintetiza las decisiones y propón el ADR.
📝 Anota durante el ejercicio
- •Cuántas preguntas ¿hizo el agente antes de la síntesis?
- •Qué 2 preguntas ¿no habías pensado y te sorprendieron?
- •Qué decisión ¿cambió de rumbo durante el grill? (señal de que el grill fue valioso)
- •Tiempo total del grill: compáralo con tu estimación inicial.
- •El ADR final ¿hay alguna decisión que no recuerdas haber tomado? Márcala para revisarla.
🎯 Criterio de éxito
El ejercicio salió bien si al final puedes responder, sin mirar:
- • ¿Qué 3 decisiones irreversibles se tomaron;
- • ¿Qué 2 decisiones quedaron explícitamente pospuestas;
- • ¿Cuál sería el siguiente paso (ejecutar /to-prd? buscar datos externos?).
Conceptos clave
✅ Resumen del módulo
Siguiente módulo:
1.3 — Del PRD a las issues: división en vertical slices