Notas de Decisão

O que Notas de Decisão faz?

Distinga claramente entre rejeição do usuário, tentativas falhas, opções não escolhidas após comparação, itens adiados e itens fora do escopo. Não trate todos eles como permanentemente inviáveis.

As notas não são para propostas não resolvidas, requisitos completos, etapas de implementação, progresso de tarefas ou registros de solução de problemas. Mantenha propostas e planos de implementação em documentos de design e plano; mantenha o comportamento atual na documentação do subsistema proprietário e verifique-o em relação ao código fonte. Mantenha a fundamentação de longo prazo nas notas; resuma e vincule a ela em outros lugares.

1. Pesquise Antes de Decisões e Mudanças

Antes de iniciar o seguinte trabalho, consulte as restrições aplicáveis do projeto, a documentação relevante do subsistema e as notas relacionadas:

• Propor uma solução concreta, definir comportamento ou fazer uma troca de design importante.
• Alterar a implementação ou testes comportamentais relacionados; para trabalho entre subsistemas, cubra as interfaces relacionadas e restrições compartilhadas.
• Criar ou alterar um registro de decisão; primeiro pesquise por conclusões existentes sobre o mesmo tópico.

Quando o usuário perguntar sobre histórico, um ponteiro de decisão for encontrado ou um conflito aparecer, leia o registro relevante diretamente. Correções puramente ortográficas, de formatação e de status não exigem uma nova pesquisa quando não envolvem restrições estabelecidas.

Localize e avalie os registros nesta ordem:

1. Use o ponto de entrada do Agente do projeto para encontrar a localização real das notas e as restrições globais aplicáveis. Use a documentação do subsistema para localizar responsabilidades atuais, contratos, código fonte, testes e notas relacionadas. Um subsistema pode abranger pacotes ou repositórios, e uma nota pode estar relacionada a vários subsistemas.
2. Siga os links e, em seguida, pesquise por pergunta, mecanismo, nome da solução e restrição conforme necessário. A ausência de um link, código correspondente ou nome correspondente não prova que não há histórico relevante. Se não houver página de subsistema, localize o contexto relevante a partir dos materiais disponíveis e do tópico da tarefa; não crie um documento vazio antecipadamente.
3. Comece pelo título, Status, Escopo e conclusão; leia a fundamentação, alternativas e evidências quando relevante. Prefira registros atualmente efetivos e, em seguida, rastreie o histórico de acordo com a relevância. Pesquise registros arquivados diretamente ao reconsiderar uma opção antiga ou quando a orientação atual for insuficiente. Rastreie a substituição de acordo com o escopo em questão; não siga uma cadeia arbitrária até o fim.
4. Confirme a aplicabilidade do registro e os fatos atuais. Se o diretório realmente não existir, continue; crie-o apenas quando um registro for necessário pela primeira vez. Uma leitura ou pesquisa falha sem correspondências não prova que não há histórico.

Dentro da mesma tarefa, reutilize resultados já verificados e ainda aplicáveis. Reavalie as partes afetadas quando o escopo, uma premissa importante ou um registro relacionado mudar, ou quando um conflito aparecer. Não varra tudo novamente apenas porque o turno ou a habilidade mudou.

Levante proativamente uma opção antiga novamente apenas quando suas premissas mudaram claramente, explicando por que não foi escolhida antes, quais condições mudaram e o impacto. Se o usuário alterar explicitamente uma decisão anterior, siga a nova instrução sem solicitar aprovação novamente. A autorização geral de implementação não cancela automaticamente uma rejeição ou restrição de escopo existente.

2. Decida se Deve Criar um Registro

Um novo registro deve atender a todas estas condições:

1. A conclusão está estabelecida. Foi adotada, rejeitada, adiada ou limitada em escopo, ou há um resultado fracassado e condições que valem a pena manter a longo prazo. Propostas não resolvidas e suposições aguardando verificação pertencem a documentos de design e planos.
2. Tem valor duradouro. Sem a fundamentação, um Agente futuro poderia levantar uma opção antiga novamente, repetir uma tentativa fracassada significativa ou alterar acidentalmente uma restrição importante. Simplesmente reafirmar o comportamento atual não atende a este limite.
3. Precisa de um registro separado. O histórico relacionado foi pesquisado e as informações não podem ser capturadas atualizando fatos, adicionando evidências ou esclarecendo o escopo. Uma mudança genuína de decisão requer um novo registro sob as regras de substituição. Não crie registros mecanicamente por data, número de entregas ou número de alternativas.

Tópicos típicos incluem limites de subsistema não óbvios, interfaces ou escolhas de persistência e compatibilidade; seleções importantes e razões para não escolher alternativas; razões para evitar deliberadamente cache ou novas tentativas automáticas; rejeições ou adiamentos significativos que possam ser levantados novamente; e conclusões de falha de longo prazo apoiadas por evidências ou políticas entre tarefas.

Geralmente, não crie notas para formatação, renomeações mecânicas, implementação ou correções comuns compreensíveis a partir do código e testes, atualizações de dependência de rotina, tentativas gerais de solução de problemas, logs, TODOs ou progresso. O tamanho não é o critério. Mantenha uma nota existente se o trabalho a tornar imprecisa e registre uma nova decisão se o trabalho produzir uma que atenda ao limite.

Se não houver um valor distinto de longo prazo a preservar, não crie um registro apenas para preencher um modelo. Se o usuário solicitar explicitamente a preservação de uma decisão importante, reutilize ou crie uma fonte apropriada; não a descarte silenciosamente.

3. Registre Conclusões Reais Rapidamente

Registre uma conclusão importante rapidamente assim que estiver clara; não espere a conclusão, o final de uma sessão ou a aprovação de commit. Uma decisão pode vir do usuário ou de um Agente fazendo uma escolha dentro da autoridade delegada. Registrar não adiciona uma etapa de aprovação, e uma troca ainda aguardando a decisão do usuário não pode ser resolvida escrevendo uma nota.

Antes de escrever, leia Formato e Exemplos. A localização padrão é .agents/notes/AAAA-MM-DD-topico.md no projeto alvo; prefira um local de projeto existente. Mantenha um tópico de decisão por arquivo e um caminho estável. Não organize notas em diretórios por status ou subsistema.

• Mantenha um título, Status e Escopo. Centralize o corpo na conclusão e na fundamentação e trocas; adicione outras seções conforme necessário. O texto do corpo padrão é em inglês, a menos que o projeto tenha um idioma consistente. Não invente alternativas, exija uma contagem fixa ou force rótulos de consequência positiva/negativa.
• Declare o escopo e as condições de cada conclusão. Não descreva um objetivo adotado, mas não implementado, como fato de implementação, migração ou implantação atual. Documentos de design e plano são responsáveis pelo progresso da implementação.
• Se a fundamentação estiver faltando, diga que não foi fornecida ou registrada. Para uma falha, retenha suas condições, resultado e evidências necessárias ou lacuna de evidências; não infira inviabilidade permanente. Não confie apenas em chat ou saída temporária que uma sessão posterior não possa acessar.

4. Atualize, Substitua e Organize

Status	Significado
active	Explicitamente adotado e ainda aplicável dentro de seu escopo declarado; rejeições e adiamentos válidos também usam este status
superseded	Todo o escopo foi substituído por uma ou mais novas decisões
retired	Nada permanece em vigor, e nenhuma nova decisão o assume totalmente

O status não indica progresso de implementação ou disposição de uma solução candidata. Se fatos, nomes, caminhos ou evidências mudarem, mas a decisão não, atualize o registro existente. Crie um novo registro quando uma escolha ou restrição central mudar claramente. Reavalie quando as evidências se tornarem inválidas; não altere a decisão automaticamente.

Antes de alterar o status, substituir uma decisão, lidar com substituição parcial ou restaurar uma opção antiga, leia Status and Supersession. Vincule registros antigos e novos por escopo; preserve restrições restantes após a substituição parcial. Se uma opção antiga for adotada novamente, crie um novo registro em vez de apagar as decisões intermediárias.

Antes de arquivar, mesclar ou excluir, leia Retention and Organization. Mantenha registros por padrão. Arquivamento lógico não move caminhos; a mesclagem não deve apagar mudanças genuínas de decisão; antes da exclusão, migre informações exclusivas e atualize referências. Organize apenas registros afetados pela tarefa atual; uma limpeza completa deve estar no escopo.

5. Verifique Antes da Entrega

Verifique registros e escopo relacionados relevantes para este trabalho. Mesmo que nenhuma nova nota tenha sido criada, verifique se as alterações tornaram uma nota existente imprecisa.

1. Omissões e duplicação: As conclusões importantes e a fundamentação de longo prazo foram salvas? Elas estão apenas em conversa? Um registro existente já é suficiente?
2. Verdade e evidências: Não apresente uma recomendação como uma decisão, um objetivo como estado atual, uma falha como rejeição permanente, uma opção não escolhida como proibida ou um adiamento como um compromisso de implementação. Declare informações desconhecidas, não fornecidas e não verificadas com precisão.
3. Status e escopo: O escopo e as condições são precisos? A substituição parcial retém as obrigações restantes? Existem conclusões eficazes conflitantes para o mesmo escopo e condições? O arquivamento oculta uma restrição atual?
4. Propriedade do documento: Atualize a documentação do subsistema afetado, designs, planos e notas; cada fonte possui suas informações, e outros locais vinculam a ela.
5. Links e cadeia de substituição: As fontes necessárias podem ser localizadas? As conclusões podem ser rastreadas por escopo sem autolinks, links quebrados ou ciclos? A organização preservou fundamentação exclusiva, evidências e referências históricas significativas?
6. Verificação: Execute verificações relevantes já disponíveis no projeto e revise seus resultados. Se nenhuma estiver configurada, verifique manualmente. Não adicione automaticamente dependências, scripts, CI ou migrações de formato. Corrija problemas reais encontrados; não fabrique conteúdo. Reutilize resultados bem-sucedidos quando o conteúdo relevante não tiver mudado.

Passar em uma verificação de formato não prova que a fundamentação está correta, a recuperação está completa ou a implementação segue a decisão. Se os fatos atuais entrarem em conflito com um registro, distinga arranjos de transição, documentação desatualizada, implementação incompleta e conflito real. Corrija erros verificados. Se um julgamento importante permanecer pouco claro, explique o conflito e peça uma decisão; não substitua uma nova instrução do usuário ou reivindique conclusão. Continue o trabalho que não depende da resposta.

Ao adicionar, atualizar substancialmente, substituir ou organizar notas, explique brevemente o que mudou, por que e quaisquer lacunas, com links. Não emita uma mensagem fixa "nenhuma nota adicionada" quando nada relevante mudou.

Mantenha código, documentação relacionada e notas juntos como uma entrega pendente. Após concluir as alterações e verificações desta rodada e mostrar os resultados, pergunte se o trabalho está completo e se um commit local pode ser criado. Se o usuário der mais feedback, continue editando. Salvar ou validar notas não autoriza um commit, push ou publicação, e não requer o commit das notas antecipadamente.