Atlas-KK/repo-grounded-change

Repo-grounded Change

Transforme um pedido de otimização para um projeto existente em uma mudança confirmada, pronta para implementação, e execute apenas a opção aprovada.

Contrato de interação e autorização

• Inspecione o repositório atual antes de recomendar uma solução. Não pergunte ao usuário sobre fatos que podem ser descobertos a partir do código, testes, configuração ou documentos de produto aplicáveis.
• Permaneça somente leitura até que o usuário aprove explicitamente uma opção ou linha de base de modificação. Diagnósticos e inspeção do repositório não autorizam edições.
• Não force este fluxo de trabalho em uma solicitação de implementação direta e inequívoca. Use a proteção quando o usuário pedir uma avaliação primeiro ou quando uma escolha afetar materialmente o comportamento, compatibilidade, risco ou escopo.
• Faça apenas perguntas que influenciam decisões. Use um controle de entrada do usuário estruturado quando disponível; caso contrário, use códigos de opção concisos como P1-A.
• Normalmente, forneça 2 ou 3 opções viáveis mutuamente exclusivas. Coloque a opção recomendada em primeiro lugar e explique o porquê. Se houver apenas uma opção segura, explique por que as alternativas foram rejeitadas em vez de inventar escolhas falsas.
• Após a confirmação, implemente a opção selecionada sem adicionar silenciosamente limpeza não relacionada. Se novos fatos do repositório alterassem materialmente o comportamento aprovado, escopo, migração, dependência ou critérios de aceitação, pare e peça uma decisão revisada.

Evidências e rótulos de decisão

Mantenha fatos separados da interpretação:

• usuário_objetivo: o ponto de dor e o resultado declarado pelo usuário.
• código_fato: comportamento observado no código fonte, testes, tempo de execução ou configuração atuais.
• documento_fato: comportamento exigido pelo documento de produto aprovado aplicável.
• técnico_recomendação: uma recomendação de implementação que preserva o comportamento pretendido do produto.
• produto_suposição: uma suposição reversível que requer confirmação.
• pendente_confirmação: uma escolha não resolvida que impede a implementação.
• já_confirmado: a opção ou linha de base explicitamente aprovada pelo usuário.
• esta_não_alterar: comportamento ou código intencionalmente fora da mudança aprovada.

A menos que o usuário especifique o contrário, use esta ordem de autoridade:

1. Instruções explícitas atuais do usuário.
2. Decisões explicitamente confirmadas na tarefa atual.
3. A especificação de produto aprovada aplicável.
4. Código e testes atuais para comportamento existente.
5. Arquivos README e documentos históricos.

Exponha conflitos; não escolha uma fonte silenciosamente.

Fluxo de trabalho

1. Descubra o comportamento atual

Leia references/discovery-and-impact.md. Inspecione apenas as áreas do repositório necessárias para reproduzir ou explicar o ponto de dor. Proteja as alterações existentes do usuário e estabeleça a linha de base atual de testes quando proporcional.

Relate o comportamento atual, o impacto no usuário, os limites de código relevantes e as evidências ausentes antes de apresentar as opções.

2. Esclareça o objetivo da mudança

Traduza a solicitação em resultados observáveis e restrições. Esclareça apenas questões que podem mudar a opção, o escopo, a estratégia de compatibilidade ou o resultado da aceitação.

Não trate a redação literal da interface do usuário como um mecanismo de implementação obrigatório quando isso introduzir semântica de interação incorreta. Explique a distinção e ofereça uma opção compatível com o repositório.

3. Compare opções viáveis

Leia references/options-and-clarification.md. Compare o impacto no produto e na engenharia, incluindo experiência do usuário, comportamento preservado, compatibilidade de estado e dados, acessibilidade, impacto nos testes, esforço de implementação, dificuldade de reversão e riscos significativos.

4. Produza a especificação da mudança recomendada

Leia references/change-spec-and-acceptance.md. A opção recomendada deve ser diretamente executável pelo Codex e incluir:

• comportamento alvo e interação;
• módulos, componentes, arquivos, interfaces e estado afetados;
• tratamento de compatibilidade, persistência, migração, degradação e reversão quando relevante;
• comportamento e dados que devem ser preservados;
• exclusões explícitas;
• plano de teste e critérios de aceitação observáveis.

Não modifique o código nesta etapa.

5. Obtenha aprovação explícita

Apresente a recomendação e as escolhas restantes. Pare depois de pedir ao usuário para selecionar uma opção ou responder à menor rodada de esclarecimento necessária.

Após a resposta, resuma a opção confirmada, as modificações do usuário, os assuntos não resolvidos, os impactos downstream e a linha de base de aceitação final. Inicie a implementação apenas quando a resposta autorizar claramente a execução, como confirmar Opção A ou executar conforme recomendação.

6. Implemente a opção aprovada

Verifique novamente a árvore de trabalho suja, preserve alterações não relacionadas e faça a menor implementação coerente. Comentários devem explicar invariantes não óbvios ou decisões de compatibilidade, não reafirmar o código.

Não exclua dados de domínio subjacentes apenas porque sua apresentação na interface do usuário foi removida, a menos que a exclusão tenha sido explicitamente aprovada. Ao alterar estados persistidos, rotas, esquemas ou enums, trate valores legados quando o repositório indicar que eles podem existir.

7. Verifique e relate

Execute testes focados primeiro, depois verificações proporcionais em todo o repositório, como verificação de tipo, lint, testes completos, build e verificação visual ou de interação da interface do usuário. Não afirme que uma verificação passou se não foi possível executá-la.

Relate o resultado implementado, os arquivos principais, as evidências de verificação, as limitações conhecidas e quaisquer avisos preexistentes não relacionados. Se uma superfície de validação solicitada não estiver disponível, divulgue-a e não contorne uma ferramenta ou ambiente explicitamente selecionado sem aprovação.

Condições obrigatórias de parada

Pare e solicite uma decisão quando:

• duas opções viáveis produzirem comportamento do usuário materialmente diferente;
• a implementação exigir uma dependência, integração, credencial, migração, ação destrutiva ou mudança de regra de negócio não aprovada;
• as alterações atuais do usuário se sobrepuserem à edição necessária e não puderem ser preservadas com segurança;
• os fatos do repositório contradisserem a opção aprovada;
• os critérios de aceitação não puderem ser tornados observáveis;
• completar a mudança com segurança exigiria expandir o escopo aprovado.

Dificuldade, duração ou detalhes comuns de implementação não são motivos para reabrir uma decisão confirmada.

Padrão de conclusão

O fluxo de trabalho está completo apenas quando a opção selecionada é implementada dentro do escopo, as decisões de compatibilidade são tratadas, os critérios de aceitação mapeiam para evidências observáveis, as verificações relevantes foram executadas e as limitações são relatadas honestamente.