Organizar o código e organizar o conhecimento são dois trabalhos, e só um deles tem lint

Depois de arrumar o repositório, o projeto deveria parecer organizado. É uma expectativa razoável: branches velhas arquivadas, scripts mortos removidos, um repositório canônico só, sem cópias concorrendo. O trabalho é visível, o diff é grande, e no fim dá para abrir a raiz do projeto sem sentir vergonha.

Fiz exatamente isso no DT Dashboard, e a limpeza foi real. Não é o caso de "faltou terminar": as branches foram arquivadas, os scripts mortos saíram, sobrou um repositório. E a sensação que veio depois foi a mesma de antes. Ainda parece desorganizado.

O problema nunca esteve no código. Estava em nunca ter existido um lugar onde uma pergunta de domínio tivesse uma resposta só.

A pergunta que interessa é onde essa sensação mora quando o repositório já está limpo.

O DT Dashboard saiu limpo da faxina e continuou parecendo bagunçado

Quando fui procurar de onde vinha o incômodo, não achei código. Achei um documento narrativo de metodologia de trading com 974 linhas, que só crescia. Achei o conhecimento sobre cada detector do motor espalhado por cinco arquivos irmãos, nenhum deles com autoridade sobre os outros. Não havia lista de aliases, então o mesmo conceito aparecia com dois nomes em lugares diferentes e ninguém sabia se eram a mesma coisa. Não havia manifesto de inventário que uma máquina pudesse ler. Não havia pipeline diário de triagem: conteúdo novo de metodologia entrava empilhado no documento de 974 linhas, porque era o único lugar.

Nada disso aparece num git status. O repositório estava limpo de verdade, e cada uma dessas lacunas continuava lá, intacta, porque a faxina nunca tinha sido sobre elas.

São dois eixos, não um

Organização de código é repositório, branches, scripts, dependências. Organização de conhecimento é outra pergunta: uma dúvida de domínio tem uma resposta única, localizável, que dá para achar sem abrir cinco arquivos irmãos e reconstruir a resposta na cabeça? Se não tem, o projeto está desorganizado, por mais limpo que o repositório esteja.

Os dois eixos avançam ou travam de forma independente. Um repositório impecável não diz nada sobre o conhecimento, e um conhecimento bem organizado pode conviver com um repositório cheio de lixo. Depois de um marco de limpeza de código, a próxima impressão de desorganização quase sempre aponta para o eixo do conhecimento, não para uma limpeza que ficou pela metade. Voltar a mexer no repositório nesse momento é fazer faxina no eixo errado.

Cinco artefatos fecham a lacuna, e nenhum deles é código

O sprint de organização de conhecimento do DT Dashboard produziu cinco coisas. Um documento canônico, um lugar definitivo em vez de cinco arquivos irmãos disputando a mesma pergunta. Arquivos de decisão por conceito (ADR), cada um com sua lista de aliases, de modo que um conceito conhecido por dois nomes aponta para o mesmo arquivo. Um manifesto de conceitos versionado, o inventário em formato que uma máquina lê, não só a narrativa em prosa. Um pipeline de ingestão, para que conteúdo novo de metodologia entre triado em vez de empilhado. E um dashboard de inventário, para ver o que está coberto e o que falta sem ler as 974 linhas inteiras.

Zero código novo saiu desse sprint. Nenhuma funcionalidade, nenhum detector, nenhuma linha no motor. Esse é o custo, e é exatamente ele que faz o trabalho ser adiado sem prazo. Um sprint inteiro sem nada para mostrar em produção é difícil de justificar. Fica difícil até o dia em que procurar onde uma decisão de domínio foi tomada custa mais do que o sprint teria custado. Recomendo pagar antes desse dia, e recomendo sabendo que a fatura chega sem nenhum item que pareça progresso.

O eixo do conhecimento não tem lint, e por isso fica invisível

Desorganização de conhecimento não vira bug. Não vira teste vermelho, não vira alerta, não vira issue. Vira uma sensação vaga de "ainda está bagunçado" que ninguém consegue apontar num arquivo específico, e sensação vaga não entra em lista de tarefas.

O reflexo natural é atacar o eixo que já é familiar. Código tem ferramentas: lint, CI, contagem de branches, tamanho do diff. Dá para medir o antes e o depois. O eixo do conhecimento não tem nada disso. Ninguém escreveu um linter que reclama quando a resposta para uma pergunta está em cinco lugares. Por isso ele fica invisível até alguém gastar um sprint inteiro só para dizer, com precisão, o que está faltando.

Cheque o outro eixo antes de mexer no repositório de novo

Depois de um marco de limpeza de código, se a impressão de desorganização persistir, a próxima parada é o eixo do conhecimento, não o repositório. Pegue uma pergunta de domínio qualquer e tente responder abrindo um arquivo só. Se precisar de cinco, o diagnóstico está feito.

A tese cai se organizar esses artefatos não reduzir a sensação de bagunça. Se ela persistir mesmo com documento canônico, aliases resolvidos e inventário legível, então os dois eixos não são independentes e o problema estava em outro lugar. É esse o teste, e ele custa menos do que outra faxina no repositório.