A documentação automatizada de repositórios é fiável?

A arqueologia de um repositório consegue recuperar uma quantidade surpreendente de documentação, mas não recupera a intenção apenas por ler mais ficheiros. Um mapa de módulos, um grafo estático de chamadas, um possível modelo de dados e grande parte do grafo de dependências de processos em lote são resultados sustentados por provas. Rótulos como "cliente", afirmações sobre quando é seguro repetir uma tarefa e explicações sobre o motivo de uma ramificação continuam a ser hipóteses até outra fonte as confirmar.

Esse limite é importante porque a documentação gerada costuma parecer igualmente segura dos dois lados. Já vi equipas aceitarem um diagrama bem apresentado, planearem uma reescrita com base nele e descobrirem tarde que uma regra do agendador ou um programa escolhido dinamicamente continha o comportamento decisivo. A solução não é rejeitar a automatização. É fazer com que cada afirmação gerada apresente as suas provas, o método e os pontos cegos conhecidos.

Um repositório prova a estrutura, não a finalidade

A documentação automatizada de repositórios é fiável quando relata uma estrutura observável e indica exatamente como a observou. Ficheiros, declarações, importações, destinos de compilação, referências SQL, instruções JCL e chaves literais de configuração deixam vestígios que podem ser inspecionados. Uma ferramenta pode enumerá-los, relacioná-los e apontar para as linhas que sustentam cada relação.

A finalidade é diferente. Uma tabela chamada ACCT_MST pode guardar contas de clientes, contas internas do razão ou um estado temporário de reconciliação. O nome sugere uma interpretação, mas não prova nenhuma. Uma rotina chamada VALIDATE pode rejeitar dados incorretos, aplicar uma regra de autorização ou apenas verificar a largura dos campos. Os comentários podem ajudar, mas um comentário desatualizado também é conteúdo do repositório, não uma verdade privilegiada.

Uso três classes de confiança na documentação gerada:

• Observado significa que o repositório contém uma prova direta, como uma importação, um EXEC PGM ou uma declaração de chave estrangeira.
• Inferido significa que várias observações sustentam uma conclusão, como agrupar programas num módulo de faturação porque partilham tabelas e pontos de entrada.
• Não resolvido significa que o repositório não permite decidir a questão, mesmo que uma interpretação pareça provável.

Cada nó e cada aresta também devem citar a sua origem como um caminho e uma linha ou intervalo de instruções. Sem proveniência, os revisores não conseguem distinguir o resultado de um analisador de uma suposição do modelo. Uma frase gerada como "INVOICE escreve em AR_LEDGER" só é útil se o leitor puder inspecionar o INSERT, a chamada ao procedimento armazenado ou a escrita de registo que a sustenta.

A distinção também evita um erro de categoria frequente: cobertura e correção são coisas diferentes. Um analisador pode encontrar corretamente todas as chamadas diretas nos ficheiros que entende e falhar chamadas feitas através de configuração. O resultado é correto dentro de um âmbito declarado, mas incompleto para o sistema em execução. A documentação deve relatar as duas dimensões, em vez de as reduzir a uma pontuação de confiança vaga.

O mapa de módulos precisa de vários tipos de aresta

Um mapa de módulos credível combina a estrutura de diretórios com provas de dependência e acesso a dados. Tratar as pastas de topo como módulos só funciona em repositórios invulgarmente disciplinados. As árvores antigas agrupam muitas vezes ficheiros por pacote de implantação, hábito de um autor, localização de copybooks ou uma migração que ficou a meio.

Comece pelas unidades declaradas: projetos, pacotes, bibliotecas, programas, formulários, procedimentos armazenados, tarefas em lote e destinos de compilação. Depois recolha arestas tipificadas entre elas. Alguns tipos úteis são imports, calls, includes, compiles_into, reads, writes, submits e generates. Preserve o tipo. Uma tabela partilhada é uma prova mais fraca de um limite de módulo do que um destino de compilação, e uma inclusão textual não é a mesma relação que uma chamada em execução.

O primeiro artefacto deve ser um inventário legível por máquinas, não uma imagem. Por exemplo:

{"unit":"billing/post_invoice.cbl","kind":"cobol_program","declares":["POSTINV"],"includes":["ARREC"],"reads":["CUSTOMER"],"writes":["AR_LEDGER"],"evidence":["billing/post_invoice.cbl:18-146"]}

Gere diagramas e texto a partir desse inventário. Assim, as alterações podem ser revistas: quando um programa muda de lugar ou um analisador melhora, o registo de origem muda primeiro e todas as vistas acompanham. A equipa também pode consultar a documentação em vez de olhar para um grafo que ocupa uma parede inteira.

O agrupamento exige contenção. Componentes ligados, declarações de pacotes, prefixos de nomes, ficheiros de propriedade e unidades de implantação podem propor limites. Não devem inventá-los silenciosamente. Se os programas AR* partilham registos e são implantados em conjunto, chame ao conjunto grupo de faturação inferido e apresente a regra que o criou. Uma pessoa poderá então aceitá-lo, dividi-lo ou mudar-lhe o nome.

O texto gerado sobre os módulos deve responder a perguntas práticas: o que entra nesta unidade? O que pode chamar? Que dados possui e em quais apenas toca? Como é compilada e implantada? Que outra unidade falharia se a interface mudasse? Um retângulo colorido que não responde a nenhuma destas perguntas é decoração.

Os grafos estáticos são úteis e previsivelmente incompletos

Um grafo estático de chamadas pode capturar com fiabilidade as chamadas cujos destinos o código resolve diretamente. Também pode fornecer arestas inversas, que costumam ser mais úteis no planeamento de alterações: em vez de perguntar o que uma função chama, os engenheiros perguntam quem consegue chegar à função que pretendem substituir.

O manual do GNU cflow faz exatamente esta distinção entre grafos diretos e inversos para C. Também disponibiliza controlos sobre a filtragem de símbolos e o pré-processamento. Essa ressalva importa. Um grafo depende do analisador da linguagem, da configuração do pré-processador, das opções de compilação e dos pontos de entrada escolhidos. Executar um analisador com as definições padrão sobre todos os ficheiros não equivale a analisar o programa que a produção compila.

O despacho dinâmico cria a primeira grande lacuna. Ponteiros de funções, reflexão, injeção de dependências, despacho COM, proxies gerados, CALL dinâmico de COBOL e nomes de programas formados a partir de dados podem esconder o destino. Um analisador de código pode registar o local do despacho e a expressão usada para selecionar um destino, mas deve criar uma aresta não resolvida em vez de adivinhar um destino.

A execução externa cria outra lacuna. Comandos de shell, APIs de submissão de tarefas, gatilhos de base de dados, consumidores de mensagens e ficheiros consultados por outro processo atravessam limites que um grafo específico de uma linguagem raramente vê. O repositório pode conter as duas extremidades sem conter uma aresta direta entre símbolos.

Registe o modo de resolução de cada aresta:

• static quando a sintaxe e a resolução de símbolos identificam o destino.
• configured quando um manifesto ou uma definição nomeia o destino.
• observed quando um rastreio de execução regista o destino.
• possible quando a análise do despacho produz um conjunto limitado.
• unknown quando existe um local de chamada, mas o destino não é resolvido.

Não elimine arestas desconhecidas para deixar o desenho mais limpo. São frequentemente os elementos mais úteis do documento porque identificam onde a migração precisa de rastreio ou de uma conversa com as operações. Um grafo com todas as chamadas resolvidas num sistema muito dependente de reflexão ou configuração costuma apenas anunciar a sua cegueira.

O modelo de dados tem três versões concorrentes

O repositório pode fornecer um esquema declarado, um esquema utilizado e um modelo de negócio implícito. Estes sobrepõem-se, mas as equipas criam problemas quando a documentação os apresenta como uma única coisa.

O esquema declarado vem de DDL, ficheiros de migração, mapeamentos ORM, definições de registos, copybooks, regras de validação e capturas de metadados da base de dados guardadas na árvore. Pode identificar tabelas, colunas, tipos, índices, chaves declaradas, nulabilidade e restrições. O PostgreSQL documenta information_schema.columns como uma vista portátil das informações das colunas, enquanto assinala que os tipos específicos do PostgreSQL residem em pg_catalog. É um aviso útil: até os metadados da base têm uma camada portátil e outra específica do fornecedor.

O esquema utilizado vem do código. Cadeias SQL, construtores de consultas, entrada e saída de ficheiros, classes de acesso a dados, ligações de ecrãs e definições de relatórios mostram os campos que cada programa lê ou escreve. Esta vista revela tabelas sem chaves estrangeiras declaradas, mas com junções consistentes, e colunas que existem em DDL, mas já não aparecem no código do repositório.

O modelo de negócio implícito acrescenta significado: uma conta pertence a um cliente, um estado C significa fechada ou um par de datas de vigência representa um período de apólice. A automatização pode propor estas relações com base em nomes, junções, verificações e transformações repetidas. Não pode promovê-las a factos sem um glossário, um teste, a confirmação de um operador ou dados observados.

Uma extração útil mantém os desacordos visíveis:

SELECT table_schema, table_name, column_name, data_type, is_nullable
FROM information_schema.columns
WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
ORDER BY table_schema, table_name, ordinal_position;

Compare esse resultado com as referências do repositório, em vez de escolher um lado como canónico. Se o código seleciona legacy_code, mas o esquema capturado não a contém, pode haver uma captura desatualizada, SQL condicional ou um esquema de produção diferente. Se o DDL declara uma chave estrangeira que nenhum código segue, a restrição continua a contar. A diferença é uma descoberta, não um incómodo a fundir até desaparecer.

A linhagem ao nível do campo exige a mesma cautela. Atribuições diretas e transformações nomeadas podem sustentar uma aresta de linhagem. Um procedimento armazenado chamado através de uma gateway genérica, uma macro de folha de cálculo ou uma exportação editada por um operador quebram a cadeia. Assinale a quebra. Não desenhe uma seta contínua através de provas em falta.

As dependências em lote vivem fora do JCL

Um repositório permite inferir grande parte do grafo de processos em lote, mas JCL ou scripts, por si só, raramente contêm o calendário de produção. Mostram programas, passos, procedimentos, conjuntos de dados, ramificações por código de retorno e submissões explícitas de tarefas. Calendários, regras de precedência, recursos, substituições e ações de recuperação costumam residir na base de dados do agendador ou na configuração operacional.

A documentação da IBM sobre o Workload Scheduler descreve predecessores e sucessores de tarefas, incluindo condições baseadas no estado ou código de retorno. A documentação do repositório JCL também diz que o agendador mantém uma cópia do JCL das tarefas submetidas no plano atual. Estes factos revelam um limite importante: o JCL submetido é um artefacto de execução, enquanto o plano atual contém o estado da orquestração. Um repositório Git que contém apenas um dos lados não consegue provar todo o grafo de dependências.

Dentro do repositório, extraia pelo menos quatro classes de arestas: ordem de passos, execução de programas, fluxo de dados e condição explícita. Uma aresta produtor-consumidor inferida porque uma tarefa escreve um conjunto de dados e outra o lê deve continuar marcada como inferida. Os nomes dos conjuntos podem ser geracionais, simbólicos, substituídos na submissão ou partilhados por motivos sem relação com a ordem.

Represente o resultado de uma forma que aceite fontes em falta:

job: CLOSE_AR
steps:
  - exec: EXTRACT_AR
    writes: [AR.CLOSE.GDG(+1)]
  - exec: POST_AR
    when: EXTRACT_AR.RC <= 4
external_predecessors:
  - name: LOAD_RATES
    source: scheduler_export
unresolved:
  - "Symbolic HLQ is supplied by the submission profile"

Esse último campo faz parte da documentação e não é motivo de embaraço. Indica à equipa de migração qual artefacto deve pedir a seguir.

Os cartões de controlo e as saídas do agendador merecem atenção especial. Um passo JCL de uma linha pode receber centenas de linhas de parâmetros a partir de um conjunto de dados mantido fora do controlo de versões. Uma saída do agendador pode reescrever variáveis ou escolher uma biblioteca de procedimentos. Trate dados de controlo referenciados, mas ausentes, como uma dependência externa com um responsável e uma tarefa de obtenção.

As provas de execução mudam a resposta

A extração estática descreve o que o repositório permite. As provas de execução mostram o que determinadas execuções fizeram. Nenhuma vista deve fingir que é a outra.

Rastreios gravados, registos de instruções da base de dados, históricos de tarefas, metadados de mensagens, catálogos de ficheiros e tráfego de produção podem confirmar destinos dinâmicos e dar prioridade aos caminhos. Podem mostrar que um despachante configurável escolheu três de vinte programas possíveis durante o período capturado. Não conseguem provar que os outros dezassete estão mortos. A ausência num rastreio significa "não observado nesta amostra", não "inalcançável".

A documentação mais forte guarda separadamente as arestas estáticas e observadas e depois apresenta a intersecção e as diferenças. Considere um local de chamada com uma lista configurada de destinos RATEA, RATEB e RATEC. Um rastreio de fecho mensal vê RATEA e RATEC. O registo correto mantém os três destinos possíveis, marca dois como observados e regista o período e o ambiente da captura. Eliminar RATEB do grafo transformaria provas limitadas numa afirmação falsa.

O tráfego de produção também ajuda a verificar o comportamento durante uma reescrita. Entradas e saídas podem tornar-se casos de paridade, desde que a captura remova ou proteja dados sensíveis e preserve as variáveis que determinam o comportamento. Um caso de paridade aprovado prova concordância para esse caso. Não estabelece equivalência geral, por isso a documentação deve indicar cobertura por ponto de entrada, ramificação, formato de dados e classe de erro, quando essas medidas estiverem disponíveis.

É aqui que a análise do repositório se torna mais do que um índice mais bonito. Um grafo estático indica onde colocar sondas. Os rastreios mostram que arestas não resolvidas merecem atenção. As diferenças entre execuções antigas e novas revelam comportamento não documentado, e essas descobertas podem regressar ao arquivo de provas.

Nunca permita que uma sobreposição de execução apague a base estática. Tarefas trimestrais silenciosas, tratadores de erros, extrações regulamentares e procedimentos de emergência podem não aparecer durante uma captura normal. As equipas chamam-lhes frequentemente código morto porque o rastreio habitual está silencioso e só descobrem a sua finalidade no único acontecimento em que são executados.

O texto gerado precisa de citações e validade

O texto gerado torna-se fiável quando um revisor consegue contestar cada afirmação material sem fazer engenharia inversa ao gerador. Coloque referências junto das afirmações e acrescente a revisão da extração, a versão da ferramenta, a configuração e a hora de geração aos metadados do documento.

O commit do repositório é a data de validade do documento. Se o ramo principal mudar, o documento gerado fica desatualizado, mesmo que o texto ainda pareça plausível. Volte a gerá-lo na integração contínua ou identifique claramente o commit que descreve. Prefiro que uma verificação de atualidade falhe a apresentar silenciosamente uma mistura de diagramas antigos e código novo.

As afirmações precisam de formas diferentes de citação. Uma afirmação estrutural pode citar linhas de código. Uma afirmação de execução deve citar um conjunto de rastreios ou uma exportação do histórico, juntamente com a janela de observação. Uma definição de negócio deve citar um glossário aprovado, uma regra, um teste ou um revisor identificado. Quando não existe citação, marque a afirmação como pergunta ou inferência.

Use um pequeno registo de revisão em vez de esconder a incerteza no texto:

ID       CLAIM                                  CLASS       EVIDENCE
DOC-041  POSTINV writes AR_LEDGER               observed    post_invoice.cbl:88
DOC-042  AR_LEDGER is the accounting system     inferred    table name, 6 writers
DOC-043  CLOSE_AR may be safely restarted       unresolved  no recovery rule found

O formato do resultado é importante porque muda o comportamento dos revisores. Se as três afirmações se transformarem em parágrafos fluentes, os leitores tendem a aceitá-las em conjunto. Um registo obriga a afirmação fraca a continuar fraca.

A validade deve ser seletiva. Um inventário de módulos pode ser regenerado em cada integração. Um significado de negócio aprovado por um operador deve persistir até a sua prova mudar, e o sistema tem de guardar a aprovação e a fonte. Uma afirmação de execução expira quando a sua janela de observação deixa de representar o uso atual. Um único carimbo de "última atualização" não consegue exprimir estas diferenças.

Repositórios multilinguagem precisam de provas comuns

Nenhum analisador consegue documentar sozinho um sistema que cruza COBOL, JCL, PL/SQL, shell, Java e macros de folhas de cálculo. Cada linguagem precisa de um componente que entenda as suas declarações e regras de resolução, enquanto o resultado combinado precisa de um vocabulário comum para unidades, pontos de entrada, ativos de dados e arestas.

A pesquisa de texto continua a ter um papel, mas deve encontrar candidatos, não afirmar relações. Procurar o nome de uma tabela pode encontrar SQL incorporado, comentários, definições copiadas, dados de teste e campos não relacionados com a mesma grafia. Um extrator que compreende a linguagem pode classificar alguns resultados. Uma fase posterior de resolução pode ligar uma chamada a uma declaração sob a configuração de compilação correta.

Normalize identidades sem apagar nomes nativos. POSTINV, o nome de um ficheiro de origem, o nome de um módulo carregável e uma operação do agendador podem referir-se ao mesmo executável em fases diferentes. Mantenha cada identificador e adicione uma relação de alias sustentada por provas. Se o alias vier apenas de uma convenção de nomes, marque-o como inferido. Fundir identidades cedo demais cria arestas falsas que depois são difíceis de separar.

As ligações entre linguagens aparecem normalmente em protocolos e artefactos, não em símbolos. Uma tarefa COBOL escreve um ficheiro simples que um script Perl lê. Um cliente VB6 invoca uma interface COM implementada em Delphi. Um procedimento armazenado escreve numa tabela de fila consultada por um serviço. Modele o ficheiro, a interface, a tabela ou a mensagem como um nó próprio. Ligar os dois programas diretamente ocultaria o contrato que realmente os acopla.

O código gerado precisa de dois registos: a entrada do gerador e o artefacto emitido que a compilação utiliza. Analisar apenas os modelos perde o comportamento emitido. Analisar apenas os ficheiros gerados torna obscuras a propriedade e a regeneração. A documentação deve mostrar que ficheiro pode ser editado e qual será substituído.

Os repositórios grandes acrescentam um problema de escala, não um problema diferente de verdade. Analise os ficheiros de forma incremental, guarde em cache resultados identificados pelo conteúdo e recalcule as arestas afetadas quando as declarações ou configurações mudarem. Não reduza o âmbito por amostragem de diretórios e chame mapa do sistema ao resultado. Uma árvore com um milhão de linhas pode ser processada em partes, mas as referências entre limites continuam a exigir resolução perante o inventário completo.

A verificação por amostra pode ser profunda

Uma equipa consegue testar a documentação gerada sem voltar a ler manualmente todo o repositório. A verificação deve fazer amostras por risco e tipo de aresta e depois usar invariantes automáticos para detetar classes amplas de falhas de extração.

Comece por casos de teste do analisador. Dê a cada extrator de linguagem pequenos exemplos de chamadas diretas, aliases, compilação condicional, despacho dinâmico, inclusões, entradas malformadas e comentários com texto semelhante a código. Confirme tanto as arestas que deve emitir como as falsas arestas tentadoras que deve rejeitar. Guarde falhas reais reduzidas como casos de regressão.

Execute invariantes em todo o repositório depois da extração. Todos os ficheiros e linhas citados têm de existir no commit analisado. Cada destino de chamada resolvido tem de possuir uma declaração ou uma identidade externa explícita. Cada membro de módulo tem de existir no inventário. Cada tipo de aresta tem de usar tipos de origem e destino permitidos. Estas verificações não provam significado, mas detetam junções quebradas e locais desatualizados antes do revisor.

Escolha depois amostras de revisão desiguais. Inspecione todas as arestas desconhecidas em pontos de entrada importantes, todas as escritas entre módulos, todas as condições do agendador e uma seleção aleatória de chamadas estáticas comuns. Faça também amostras do espaço negativo: escolha mecanismos dinâmicos conhecidos e confirme que o documento mostra a sua incerteza. Uma precisão medida apenas em chamadas diretas fáceis recompensa o sistema errado.

Um relatório compacto de aceitação pode incluir números úteis sem os transformar numa classificação de qualidade:

Analyzed commit: 7c41e2f
Parsed files: 18,442 of 18,517 discovered
Skipped files: 75 (list attached to the evidence store)
Resolved call edges: 91,208
Unknown dispatch sites: 613
Broken citations: 0
Scheduler sources: repository JCL only; current-plan export absent

Os números são um exemplo do formato de saída, não uma referência de desempenho. As linhas importantes são o denominador, a lista de ficheiros ignorados e a fonte ausente do agendador. Comunicar "18 442 ficheiros analisados" sem dizer que 75 foram ignorados deixa uma falha do analisador desaparecer num total grande.

As correções da revisão devem atualizar regras ou provas, não apenas o parágrafo apresentado. Se um revisor identificar um alias falso, adicione uma restrição que impeça a fusão na próxima vez. Se um operador confirmar uma definição de negócio, guarde a aprovação como uma fonte separada. Caso contrário, a regeneração recriará fielmente cada erro já corrigido.

A confiança termina nos limites dinâmicos e humanos

A documentação automatizada deixa de ser fiável nos limites onde o repositório não contém a informação decisiva. Os principais limites são a seleção dinâmica, o estado externo, o código gerado ou ausente, a intervenção operacional, a configuração específica do ambiente e a intenção de negócio.

Pode transformar essa afirmação numa lista de verificação:

1. Resolva todos os artefactos referenciados. Encontre ficheiros incluídos, fontes geradas, bibliotecas de procedimentos, cartões de controlo, esquemas e manifestos de implantação. Registe tudo o que estiver ausente.
2. Compare a compilação real com a organização do repositório. Registe opções do compilador, símbolos condicionais, passos de geração de código e as unidades exatas de implantação.
3. Sobreponha provas de execução sem as tratar como exaustivas. Mantenha a janela da amostra e o ambiente junto de cada aresta observada.
4. Pergunte às operações sobre reinício, fecho, substituição e caminhos de exceção. Estas regras vivem muitas vezes em manuais, consolas do agendador ou na memória.
5. Exija uma fonte identificada para os rótulos de negócio. Uma expansão plausível de um nome de campo com oito caracteres continua a ser uma suposição.

Uma recomendação popular é pedir a um modelo de linguagem que leia o repositório e escreva um manual de arquitetura completo de uma só vez. É popular porque o primeiro resultado é rápido e coerente. Está errada porque a coerência elimina as divisões visíveis entre factos analisados, interpretações e omissões. Use um modelo para explicar um grafo, agrupar provas e formular perguntas, mas mantenha o grafo de provas como autoridade.

Os limites de segurança e acesso podem criar outro ponto cego. Um analisador que não consegue ler exportações do agendador de produção, configurações cifradas ou catálogos da base de dados deve declará-lo no início. A falta de acesso não pode transformar-se na ausência de uma dependência.

O teste prático de aceitação é simples: selecione afirmações ao acaso e siga as respetivas citações. Se os revisores não conseguem reproduzir as afirmações estruturais, o sistema não está pronto. Se conseguem reproduzi-las, mas discordam do texto, corrija a regra de inferência ou a redação sem descartar as provas extraídas.

A documentação deve orientar o plano de reescrita

A documentação do repositório justifica o custo quando altera a sequência, os testes e o âmbito. Um mapa de módulos deve identificar unidades substituíveis de forma independente e nós de estado partilhado. Um grafo inverso de chamadas deve revelar chamadores que precisam de cobertura de compatibilidade. O modelo de dados deve identificar disputas de propriedade e acoplamento oculto. O grafo de processos em lote deve expor fechos e caminhos de recuperação que uma reescrita em serviços precisa de preservar.

Para planear a migração, consulte as provas em vez de as ler do princípio ao fim. Pergunte que pontos de entrada chegam a um módulo candidato, que tabelas atravessam o limite proposto, que tarefas em lote o invocam e que arestas continuam por resolver. Uma aresta não resolvida num caminho diário de liquidação merece trabalho antes de um utilitário de relatórios totalmente mapeado, mesmo que o utilitário tenha mais linhas.

A modernização da arquitetura também exige uma base de comportamento. Traduzir cada programa antigo para uma nova linguagem conserva limites acidentais e faz com que os diagramas gerados pareçam familiares, mas familiaridade é um mau critério de desenho. Use pontos de entrada observados, contratos de dados, efeitos secundários e restrições de ordem para definir compatibilidade. Depois desenhe os serviços de destino em torno de uma propriedade coerente.

A CodeHero usa esta combinação ao reescrever sistemas antigos: a plataforma lê toda a árvore multilinguagem e um mecanismo de paridade compara o substituto com tráfego de produção gravado. Isto não transforma uma finalidade inferida num facto. A extração estrutural e as provas de comportamento recebem funções separadas, que é a disciplina exigida por uma reescrita.

Antes de aprovar um documento gerado, exija resposta para uma pergunta concreta: que afirmações mudariam se amanhã chegassem a exportação do agendador, o rastreio de execução ou a entrevista com as operações? Se o documento não consegue identificá-las, escondeu a incerteza em vez de a gerir. Um repositório pode produzir um mapa excelente, mas as áreas em branco têm de continuar visíveis até serem preenchidas por provas.

Conserve o inventário de provas depois da entrega da reescrita. Torna-se um oráculo de regressão para alterações de dependências, uma fonte de documentação operacional e uma verificação contra novo acoplamento acidental. O texto pode envelhecer, mas os factos reproduzíveis ligados a commits podem ser regenerados sempre que o sistema mudar.