amadeus-grilling

O que amadeus-grilling faz?

Propósito

Eliminar ambiguidades em planos e designs, uma de cada vez, através de perguntas.

Percorrer os ramos da árvore de design em ordem até que um entendimento compartilhado seja alcançado. Decisões interdependentes são resolvidas uma a uma, desfazendo as dependências.

Postura Básica

As perguntas devem ser rigorosas. No entanto, não se deve tornar o aumento de perguntas um objetivo em si.

Pergunte apenas sobre pontos que o usuário precisa decidir para prosseguir. O que pode ser respondido a partir da base de código, artefatos .amadeus/, documentação existente ou conversas anteriores, você mesmo verifica sem perguntar.

Como Fazer Perguntas

Faça uma pergunta de cada vez. Apresentar várias perguntas de uma só vez dificulta entender por qual decisão começar.

Cada pergunta deve incluir:

• O que precisa ser decidido.
• Por que essa decisão é necessária agora.
• A resposta recomendada.
• A razão para a recomendação.

Após fazer a pergunta, aguarde a resposta do usuário. Não prossiga para a próxima pergunta antes de receber a resposta.

Resposta Recomendada

Cada pergunta deve vir acompanhada de uma resposta recomendada.

A resposta recomendada deve ser baseada nos artefatos atuais, nos limites do design, nos riscos de implementação e no impacto nas tarefas subsequentes. Se não for possível recomendar, indique o motivo e as informações faltantes necessárias para a decisão.

Prioridade de Investigação

Se a pergunta puder ser respondida investigando a base de código ou artefatos, investigue primeiro.

Exemplos de alvos de investigação:

• .amadeus/
• README.md
• AGENTS.md
• AMADEUS.md
• Habilidades existentes
• Artefatos de Intent existentes
• Domínios, glossários, decisões, rastreabilidade existentes

Após investigar, pergunte apenas se ainda for necessária uma decisão humana.

Grilling Decision Trail

Nos modos guided ou refine, quando ocorrerem perguntas e respostas que afetem o significado de artefatos ou decisões subsequentes, registre o processo decisório confirmado como um Grilling Decision Trail.

O Grilling Decision Trail não é um log bruto. Declarações não confirmadas, propostas descartadas, meras autorizações de execução, confirmações leves de ordem de trabalho, confirmações de execução de comandos ou conveniências temporárias não são registradas.

São registradas as seguintes decisões:

• Escopo.
• Critérios de sucesso.
• Fora de escopo.
• Dependências.
• Terminologia.
• Contextos Delimitados (Bounded Contexts).
• Estratégia de divisão.
• Julgamento de estado.
• Destino de reflexão.
• Decisões de supersedência.

amadeus-grilling define os critérios de registro, estrutura, estado e numeração. A criação ou atualização real de grillings.md e grillings/Gxxx-*.md é feita pela habilidade de fase que chamou o grill.

No turno em que a pergunta é feita, não atualize artefatos. No turno seguinte ao recebimento da resposta do usuário, a habilidade de fase interpreta a resposta dentro dos limites de seu artefato e atualiza o Grilling Decision Trail junto com a reflexão no artefato da fase.

A localização é na raiz do conjunto de artefatos alvo.

<raiz alvo>/
  grillings.md
  grillings/
    G001-<topico>.md

A raiz alvo é:

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

A Steering Layer está excluída deste registro devido à estrutura mista atual em .amadeus/.

Decisões que afetam apenas o domínio geral ou termos compartilhados não criam um Grilling Decision Trail dedicado na estrutura atual. Se necessário, registre em .amadeus/domain-map.md, .amadeus/context-map.md, .amadeus/glossary.md como justificativa ou decisão do Intent alvo.

grillings.md trata apenas do índice. Os detalhes da sessão ficam em grillings/Gxxx-*.md.

grillings.md possui a seguinte estrutura mínima:

# Grillings

## Lista

| ID | Tópico | Alvo | Estado | Decisão Principal | Destino | Detalhes |
|---|---|---|---|---|---|---|
| G001 | Ideation Scope | Intent | completed | Escopo limitado à tela de administração | [scope.md](scope.md) | [G001](grillings/G001-ideation-scope.md) |

O nome do arquivo de sessão deve ser G001-<topico>.md. <topico> deve conter apenas letras minúsculas, números e hífens.

O estado da sessão deve ser um dos seguintes:

• active
• completed
• superseded

O estado de uma decisão individual deve ser um dos seguintes:

• active
• superseded

O arquivo de sessão deve conter Resumo, Decisões Confirmadas e Registro de Perguntas. O Resumo deve incluir obrigatoriamente o destino de toda a sessão. Os destinos do Resumo e das decisões individuais devem apontar para artefatos dentro da raiz alvo. Em Discovery e Event Storming, permite-se apontar para <id>.md pai a partir de <id>/grillings (ex.: ../<id>.md). Apenas quando um Grilling Decision Trail sob o domínio geral apontar para .amadeus/glossary.md, permite-se ../glossary.md como reflexão em termo compartilhado. Cada registro de pergunta deve conter obrigatoriamente: O que precisa ser confirmado, Por que a confirmação é necessária, Resposta recomendada, Motivo da recomendação, e Resposta do usuário. Cada registro de pergunta deve referenciar obrigatoriamente o ID da decisão confirmada. Decisões individuais devem indicar obrigatoriamente o destino. Decisões individuais superseded devem indicar obrigatoriamente o substituto.

No modo scaffold-only, não há perguntas, portanto não se cria Grilling Decision Trail. No modo repair, em princípio, não se atualiza o Grilling Decision Trail. No entanto, se grillings.md ou grillings/Gxxx-*.md existentes estiverem corrompidos, pode-se corrigi-los como reparo estrutural.

Continuação de Discussões Prolongadas

Se a grill se prolongar e for mais seguro continuar em outra unidade de conversa, use handoff como auxílio operacional.

handoff não é um artefato do Amadeus DLC. O documento de handoff criado deve ser colocado no diretório temporário do SO, não em .amadeus/.

Decisões confirmadas permanecem no Grilling Decision Trail. No handoff, escreva apenas as referências necessárias para retomar na próxima unidade de conversa.

O handoff deve conter no mínimo:

• O workspace alvo e o conjunto de artefatos alvo.
• Os grillings.md e grillings/Gxxx-*.md a serem consultados.
• Um resumo das decisões já confirmadas.
• As perguntas não respondidas e a próxima a ser verificada.
• A habilidade recomendada para a próxima unidade de conversa.

Não duplique no handoff conteúdo já escrito em artefatos existentes. Se artefatos, PRs, Issues, diffs ou resultados de verificação existirem, referencie-os por caminho ou URL.

Onde Usar no Amadeus

Use nas seguintes situações:

• Verificar propósito, atores, restrições e domínios da Steering Layer.
• Verificar propósito, dependências, critérios de sucesso e escopo de um Intent.
• Verificar alvo, fora de escopo, viabilidade, equipe, mock inicial e transferência para Inception de uma Ideação.
• Verificar significado de termos, conceitos, Contextos Delimitados, modelos DDD e contratos.
• Verificar granularidade e motivos de exceção de Units, Bolts e Specs.

Proibições

• Não faça várias perguntas de uma só vez.
• Não pergunte o que pode ser aprendido lendo artefatos existentes.
• Não pergunte sem incluir uma resposta recomendada.
• Não atualize artefatos no turno em que a pergunta foi feita, antes de receber a resposta.
• Não registre a resposta do usuário de forma que contradiga artefatos existentes. Se houver contradição, explique-a primeiro e confirme.