amadeus-grilling

¿Qué hace amadeus-grilling?

Propósito

Eliminar la ambigüedad de planes y diseños mediante preguntas, una por una. Recorrer las ramas del árbol de diseño en orden hasta alcanzar un entendimiento compartido. Las decisiones que dependen unas de otras se resuelven una a una, desenredando las dependencias.

Postura básica

Las preguntas deben ser rigurosas. Sin embargo, el objetivo no es aumentar la cantidad de preguntas por sí mismo.

Solo preguntar aquellos puntos que el usuario deba decidir para poder avanzar. Lo que pueda responderse consultando la base de código, los artefactos de .amadeus/, la documentación existente o conversaciones anteriores, se debe verificar sin preguntar.

Cómo formular preguntas

Las preguntas se hacen una por una. Si se presentan varias preguntas a la vez, resulta difícil saber por qué decisión empezar.

Cada pregunta debe incluir:

• Qué se quiere decidir.
• Por qué es necesaria esa decisión ahora.
• Una respuesta recomendada.
• La razón de la recomendación.

Una vez hecha la pregunta, esperar la respuesta del usuario. No pasar a la siguiente pregunta antes de recibir respuesta.

Respuesta recomendada

Toda pregunta debe incluir una respuesta recomendada.

La respuesta recomendada se elabora considerando los artefactos actuales, los límites del diseño, los riesgos de implementación y el impacto en el trabajo posterior. Si no es posible hacer una recomendación, se debe explicar el motivo y señalar la información faltante necesaria para decidir.

Priorizar la investigación

Si una pregunta puede responderse investigando la base de código o los artefactos, primero se investiga.

Ejemplos de qué investigar:

• .amadeus/
• README.md
• AGENTS.md
• AMADEUS.md
• Skills existentes
• Artefactos de Intent existentes
• Dominios, glosarios, decisiones, trazabilidad existentes

Solo si tras investigar aún se necesita un juicio humano, se formula la pregunta.

Grilling Decision Trail

Cuando en las fases guided o refine surjan preguntas y respuestas que afecten el significado de los artefactos o decisiones posteriores, se registrará el proceso de decisión confirmado como Grilling Decision Trail.

El Grilling Decision Trail no es un registro en bruto. No se registran comentarios no confirmados, propuestas descartadas, meros permisos de ejecución, confirmaciones ligeras de orden de trabajo, confirmaciones de ejecución de comandos, ni conveniencias temporales.

Se registran decisiones como:

• Alcance.
• Criterios de éxito.
• Exclusiones.
• Dependencias.
• Terminología.
• Contextos acotados.
• Criterios de división.
• Juicios de estado.
• Destinos de aplicación.
• Decisiones de suprasión.

amadeus-grilling es el estándar para qué registrar, la estructura de registro, el estado y la numeración. La creación o actualización del grillings.md y grillings/Gxxx-*.md reales la realiza la skill de fase que invocó el grill.

En el turno en que se pregunta, no se actualizan artefactos. En el turno siguiente a recibir la respuesta del usuario, la skill de fase interpreta la respuesta dentro de su propio límite de artefactos y actualiza el Grilling Decision Trail junto con los mismos cambios que se reflejan en los artefactos de la fase.

La ubicación es directamente bajo la raíz del conjunto de artefactos objetivo.

<raíz objetivo>/
  grillings.md
  grillings/
    G001-<tema>.md

La raíz objetivo es:

.amadeus/discoveries/<id-descubrimiento>/
.amadeus/event-storming/<id-event-storming>/
.amadeus/intents/<id-intent>-<slug>/
.amadeus/intents/<id-intent>-<slug>/event-storming/<id-event-storming>/

La capa de dirección (steering layer) queda excluida de este registro debido a que la estructura actual bajo .amadeus/ está mezclada.

Las decisiones que solo afectan al dominio general o a la terminología compartida no crean un Grilling Decision Trail dedicado en la estructura actual. Si es necesario, se deja constancia en .amadeus/domain-map.md, .amadeus/context-map.md o .amadeus/glossary.md como fundamento, o en la decisión del Intent correspondiente.

grillings.md solo contiene el índice. Los detalles de las sesiones se colocan en grillings/Gxxx-*.md.

grillings.md tiene la siguiente estructura mínima:

# Grillings

## Lista

| ID | Tema | Objetivo | Estado | Decisión principal confirmada | Destino | Detalle |
|---|---|---|---|---|---|---|
| G001 | Alcance de Ideación | Intent | completado | Limitar el alcance a la pantalla de administración | [scope.md](scope.md) | [G001](grillings/G001-ideation-scope.md) |

El nombre del archivo de sesión debe ser G001-<tema>.md. <tema> debe escribirse solo con letras minúsculas en inglés, números y guiones.

El estado de la sesión puede ser uno de los siguientes:

• active
• completed
• superseded

El estado de una decisión individual puede ser uno de los siguientes:

• active
• superseded

El archivo de sesión debe contener: Resumen, Decisiones confirmadas y Registro de preguntas. En Resumen se debe escribir obligatoriamente el destino de toda la sesión. El destino en Resumen y en cada decisión individual apunta a artefactos dentro de la raíz objetivo. En Discovery y Event Storming, se permite que <id>/grillings apunte al Markdown padre con el mismo ID mediante ../<id>.md. Sin embargo, solo se permite apuntar a ../glossary.md como reflejo en la terminología compartida cuando el Grilling Decision Trail bajo el dominio general apunte a .amadeus/glossary.md. Cada registro de pregunta debe incluir obligatoriamente: Qué se quiere confirmar, Por qué es necesario confirmarlo, Respuesta recomendada, Razón de la recomendación y Respuesta del usuario. Cada registro de pregunta debe referenciar obligatoriamente el ID de la decisión confirmada. Cada decisión individual debe incluir obligatoriamente su destino. Las decisiones individuales con estado superseded deben incluir obligatoriamente el destino de reemplazo.

En la fase scaffold-only no se hacen preguntas, por lo tanto no se crea Grilling Decision Trail. En la fase repair, en principio no se actualiza el Grilling Decision Trail. Sin embargo, si el grillings.md o grillings/Gxxx-*.md existente está dañado, se puede reparar su estructura.

Transferencia de discusiones prolongadas

Si el grilling se alarga y es más seguro continuar en otra unidad de conversación, se utiliza handoff como ayuda operativa.

handoff no es un artefacto de Amadeus DLC. El documento de transferencia creado se coloca en el directorio temporal del sistema operativo, no bajo .amadeus/.

Las decisiones confirmadas se dejan en el Grilling Decision Trail. handoff solo debe contener las referencias necesarias para reanudar en la siguiente unidad de conversación.

handoff debe incluir al menos:

• El workspace objetivo y el conjunto de artefactos objetivo.
• El grillings.md y grillings/Gxxx-*.md que se deben consultar.
• Un resumen de las decisiones ya confirmadas.
• Las preguntas sin responder y la siguiente pregunta a abordar.
• La skill recomendada para la siguiente unidad de conversación.

No duplicar en handoff el contenido que ya está escrito en los artefactos existentes. Si existen artefactos, PRs, Issues, diferencias o resultados de verificación, referenciarlos mediante ruta o URL.

Cuándo usar en Amadeus

Se utiliza en situaciones como:

• Confirmar el propósito, los actores, las restricciones y el dominio de la capa de dirección (steering layer).
• Confirmar el propósito, dependencias, criterios de éxito y alcance de un Intent.
• Confirmar el alcance, exclusiones, viabilidad, equipo, mock inicial y transferencia a Inception de una Ideación.
• Confirmar términos, conceptos, contextos acotados, modelos DDD y el significado de contratos.
• Confirmar la granularidad o las razones de excepción de Units, Bolts y Specs.

Prohibiciones

• No presentar varias preguntas a la vez.
• No preguntar algo que se pueda averiguar leyendo los artefactos existentes.
• No preguntar sin ofrecer una respuesta recomendada.
• No actualizar artefactos en el turno en que se formula la pregunta, sin esperar la respuesta.
• No confirmar la respuesta del usuario de forma que contradiga los artefactos existentes. Si hay contradicción, explicarla primero y confirmar.