write-adr

name

write-adr

description

Cria, revisa, ratifica ou atualiza Architecture Decision Records em YAML canônico, com Markdown gerado, alternativas reais, trade-offs, riscos, mitigação, histórico e gate de qualidade. Use para registrar uma decisão arquitetural, documentar por que uma escolha foi feita, criar ADR a partir de outro artefato, revisar uma ADR existente ou marcar uma decisão como rejeitada, obsoleta ou substituída. Não usar para guidelines, tutoriais, runbooks ou planos de implementação.

Write ADR

Registre o porquê de uma decisão para que ele sobreviva ao contexto original. Grave o YAML em decisions/ como fonte canônica e gere o Markdown em generated/adrs/; nunca edite os dois em paralelo.

Conduza o fluxo pelo diálogo e execute os scripts internamente. Não peça ao usuário para operar Node ou terminal, salvo em troubleshooting solicitado.

Contratos obrigatórios

Leia antes de escrever:

• references/contracts.md: campos, formato e comandos.
• references/quality-gate.md: requisitos por estado.
• references/lifecycle.md: preservação de histórico e supersessão.

Use assets/adr-template.yaml somente como referência estrutural. Não reutilize o ID ou a data do exemplo.

Princípios

• Registre uma decisão por ADR.
• Declare a decisão diretamente: Adotamos..., Mantemos... ou Não permitimos....
• Registre alternativas reais, inclusive manter o estado atual quando aplicável.
• Explicite ganho, custo aceito, risco, tratamento, responsável e gatilho observável.
• Identifique os decisores antes de aceitar a ADR.
• Nunca invente contexto, motivação, evidência, consenso ou responsável.
• Use status: proposed e pending enquanto faltar informação material.
• Preserve ADRs antigas; decisões novas substituem, não reescrevem, decisões anteriores.

Fronteira

Inclua contexto, decisão, escopo, alternativas, trade-offs, consequências, riscos e revisão. Mantenha instalação, código extenso, procedimento, backlog, guideline e runbook em artefatos próprios, ligados por referências.

Fluxo

1. Localizar o repositório

Exija um diretório com architecture.yaml. Não grave dados de execução dentro do plugin.

2. Criar o rascunho

Execute:

node <skill>/scripts/create-adr.mjs --data-dir <architecture-data> --title <título> --scope-type <tipo> --scope-id <id>

O script reserva o próximo ID e cria uma ADR proposed sem sobrescrever arquivos.

Para aprovar, rejeitar ou mover um blip, use o gerador especializado:

node <skill>/scripts/create-radar-adr.mjs --data-dir <architecture-data> --blip <slug> --action <approve|reject|move> [--to-ring <ring>]

Ele captura o estado anterior, adiciona radar_change, evidência e relação governs. Não altera o blip; a skill tech-radar aplica somente a ADR aceita.

3. Recuperar o racional real

Preencha somente informações sustentadas pelo usuário ou por artefatos referenciados. Priorize:

1. decisão concreta;
2. problema, restrição ou risco que a motivou;
3. alternativas consideradas;
4. ganho e perda aceitos;
5. riscos e tratamento;
6. decisores e escopo;
7. indicadores e gatilhos de revisão.

Não substitua lacunas por benefícios genéricos. Registre cada lacuna em pending.

4. Desafiar

Verifique se a decisão resolve o problema, se as alternativas são comparáveis, se há consequência negativa omitida, se as mitigações têm responsável e se existe condição de revisão ou reversão.

5. Validar

Execute:

node <skill>/scripts/validate-adr.mjs --file <adr.yaml>

Não marque como accepted enquanto o gate falhar. Uma ADR aceita não pode manter pending.

6. Renderizar

Execute:

node <skill>/scripts/render-adr.mjs --data-dir <architecture-data> --file <adr.yaml>

Entregue os caminhos do YAML canônico e do Markdown gerado. Para revisão, apresente primeiro problemas de decisão ambígua, racional ausente, alternativas fracas, trade-offs omitidos e riscos sem tratamento.

7. Atualizar o grafo

Depois de renderizar ou aplicar uma ADR, gere novamente a projeção com <skill>/../../shared/scripts/generate-graph.mjs --data-dir <architecture-data>. Reporte ADR isolada como ponto de revisão, não como defeito automático: nem toda decisão exige guideline. Nunca invente guideline ou guardrail para silenciar alerta.