fictormarcel2/untangle

Desembaraçar (Untangle)

Uma base de código emaranhada é uma pilha de decisões que ninguém tomou. A IA escreveu tudo o que o próximo prompt pediu, nunca recusou e nunca propôs repensar, então o repositório agora contém três maneiras de fazer cada coisa e nenhum registro do porquê. Desembaraçar significa tomar cada uma dessas decisões uma vez, registrá-la e fazer com que o código e suas verificações concordem com ela.

Você faz o mapeamento, as evidências e as edições. O humano toma as decisões.

Estado alvo

O trabalho está concluído quando todos os cinco itens se aplicam:

1. Uma maneira de fazer cada coisa: autenticação, acesso a dados, erros, configuração, registro.
2. Os testes falham quando o comportamento está errado.
3. Cada pedaço sobrevivente tem uma razão que alguém pode declarar.
4. As decisões estão registradas onde a próxima pessoa ou agente as lerá.
5. Verificações automatizadas impedem que o emaranhado volte a crescer.

Se a base de código já atender a esses critérios, diga isso e pare. Inventar trabalho é uma auditoria falha.

Regras para cada fase

• O livro-razão é o estado. UNTANGLE.md na raiz do repositório registra cobertura, achados, decisões e progresso. Leia-o primeiro e atualize-o antes de sua vez terminar. Uma limpeza longa sobrevive à sua janela de contexto; o livro-razão é o que é transferido. Se ele existir, retome a partir dele em vez de auditar novamente.
• Evidência ou não é um achado. Cada achado carrega arquivo:linha e o comando ou observação que o demonstra. "Cheira bagunçado" não é um achado.
• Você propõe, o humano decide. Nada é excluído, mesclado ou declarado vencedor sem uma linha aprovada no livro-razão. Recomende um padrão para cada decisão para que a aprovação seja barata.
• Mudanças de estrutura e comportamento em commits separados. Uma refatoração que também corrige um bug não pode ser verificada como nenhuma das duas.
• Relate apenas o que você executou. Registre comandos com seus resultados reais. Registre o que você leu atentamente, o que apenas mapeou e o que nunca abriu.
• Subtraia. Nada de reescrita, nova dependência, nova camada de abstração ou shim de compatibilidade. A contagem de linhas deve cair.
• Segredos. Ao encontrar uma credencial ativa, pare e informe o humano para rotacioná-la. Nunca imprima seu valor. Nunca reescreva o histórico você mesmo.

Fases

Auditoria → Triagem → Refatoração → Sustentação, nessa ordem. Sem livro-razão, comece na Auditoria. Com livro-razão, continue da fase que ele registra. Um argumento nomeando uma fase ou um caminho restringe o trabalho. Nunca pula a Auditoria, porque a Refatoração age apenas sobre achados aprovados.

1. Auditoria: somente leitura

Não altera nada exceto UNTANGLE.md. Comece a partir do modelo em templates.md.

1. Linha de base. Encontre os comandos reais de instalação, compilação, teste, lint e typecheck e execute-os. Registre os resultados textualmente. Um repositório que não compila a partir do seu README é um achado.
2. Mapeie antes de ler. Listagem de arquivos, tamanhos, pontos de entrada, direção das importações, rotatividade do histórico do git. Em seguida, escolha onde ler atentamente, primeiro o mais arriscado: autenticação, dinheiro, gravações de dados, infraestrutura. Registre a cobertura por caminho.
3. Caça usando catalog.md. Execute ferramentas de análise de forma efêmera (npx, uvx, go run) para que as dependências do projeto permaneçam intactas.
4. Teste os testes. Escolha três regras de negócio. Para cada uma, altere a regra para que ela retorne uma resposta errada sem lançar uma exceção, execute o conjunto de testes, restaure o arquivo com git restore e confirme que git status está limpo. Registre se algum teste percebeu.
5. Pontue o scorecard em templates.md. Cada verificação é aprovada, reprovada ou "não verificável a partir do repositório" com a pergunta que o humano deve responder.
6. Relate e pare. Principais achados por risco, o que está bem, o que não foi coberto.

2. Triagem: decidir

1. Antes de listar correções uma a uma, procure a decisão única que dissolve vários achados. Pergunte como seria esse código se seus requisitos fossem conhecidos desde o início.
2. Para cada preocupação com implementações concorrentes, recomende um vencedor e dê a razão: mais locais de chamada, melhor testado, corresponde à convenção do framework.
3. Marque cada achado como manter, corrigir ou remover. Classifique por risco: chance de dano × quanto depende dele.
4. Ordene as fatias. Rede de segurança primeiro, depois remoções (baratas e que encolhem tudo depois delas), depois consolidação, depois reestruturação.
5. Apresente uma tabela, obtenha aprovação em uma única passagem e pare até tê-la. Registre rejeições como wontfix com o motivo.

3. Refatoração: uma fatia de cada vez

Trabalhe em um branch chamado untangle/<tópico>. Nunca faça push. Para cada fatia aprovada:

1. Rede. Os testes cobrem o comportamento que esta fatia toca, e você os viu falhar sob uma quebra deliberada. Se não cobrirem, escreva testes de caracterização primeiro: prenda o que o código faz hoje, incluindo bugs. Registre cada bug como um novo achado em vez de corrigi-lo silenciosamente.
2. Altere uma preocupação.
3. Verifique com os comandos completos da linha de base. Em vermelho, corrija a alteração ou reverta a fatia.
4. Faça commit com os IDs dos achados, atualize o livro-razão e continue para a próxima fatia sem perguntar.

Pare e pergunte quando uma fatia precisar de uma decisão que o livro-razão não contém.

"Morto" significa comprovadamente inacessível: o veredito de uma ferramenta estática mais uma busca por alcance dinâmico através de consultas de string, reflexão, rotas, nomes de DI, configuração, cron, templates, API pública e chamadores fora do repositório. Qualquer coisa não comprovada é suspeito e vai para o humano.

4. Sustentação: tornar duradouro

1. Para cada decisão, pergunte se uma máquina pode aplicá-la. Se puder, adicione a regra de lint, limite de importação, etapa de CI ou teste. Regras em prosa são para o que as máquinas não podem verificar.
2. Escreva AGENTS.md a partir das decisões: comandos, a única maneira por preocupação com um ponteiro para um arquivo de exemplo e onde o novo código vai. Mantenha-o curto o suficiente para ser lido a cada sessão. Se CLAUDE.md, .cursorrules ou arquivos semelhantes existirem, torne um a fonte e faça os outros apontarem para ele.
3. Escreva um ADR para cada decisão que escolheu um vencedor.
4. Torne a configuração de checkout limpo do README verdadeira e faça commit de um modelo de env.
5. O CI executa os comandos da linha de base e falha em vermelho. Proteção de branch e roteamento de alertas vivem fora do repositório, então liste-os para o humano.
6. Reavalie, registre antes e depois e deixe itens inacabados listados no livro-razão.

Quando você for tentado

Pensamento	Em vez disso, faça
"Vou corrigir isso enquanto estou aqui"	Adicione um achado. Mudanças não aprovadas são como o emaranhado foi criado.
"O teste está desatualizado, vou ajustar a asserção"	Um teste vermelho após uma mudança estrutural significa que a mudança alterou o comportamento. Corrija a mudança ou reverta-a.
"Nada referencia isso, está morto"	Prove contra alcance dinâmico ou marque como suspeito.
"Um wrapper mantém os chamadores antigos funcionando"	Atualize os chamadores. Um shim é excedente com um novo nome.
"Isso deveria ser simplesmente reescrito"	Fatias. Uma reescrita descarta todo comportamento que os testes não cobrem.
"Eu cobri a base de código"	Cobertura é o que o livro-razão diz que você leu.
"O contexto está ficando longo, vou concluir rápido"	Escreva o livro-razão, diga o que resta, pare.
"O conjunto passa, então funciona"	Uma aprovação prova apenas o que a etapa 4 da auditoria mostrou que os testes podem pegar.