Sincronização de Documentação

O que Sincronização de Documentação faz?

Código e seus documentos mudam juntos, no mesmo commit. Um documento errado é pior que nenhum documento.

Três formas como documentos ficam errados

• Desatualizado. O documento ainda descreve o comportamento, nome ou comando antigo.
• Ausente. Um novo comportamento, comando ou configuração não tem documentação.
• Duplicado. O mesmo fato está em dois lugares. Depois, uma cópia muda e a outra não.

Passos

1. Veja o que mudou.

   git diff --cached --stat
   git diff --stat
   

2. Encontre as regras do próprio repositório. Leia CLAUDE.md, CONTRIBUTING.md e docs/README.md. Se eles disserem qual documento é dono de qual assunto, siga-os. Eles vêm antes do passo 3.
3. Roteie cada mudança ao seu dono. Use resources/doc-routing.md. Um fato tem um lar. Outros documentos linkam para ele.
4. Encontre referências desatualizadas. Para cada nome que você renomeou ou removeu (uma função, flag, endpoint, configuração, caminho de arquivo, comando):

   git grep -n '<nome antigo>'
   

   Corrija cada ocorrência em um documento. Execute o grep novamente. A pós-condição é: nenhuma ocorrência, ou apenas ocorrências que devem permanecer (por exemplo, uma entrada no CHANGELOG sobre a renomeação).
5. Edite. Altere apenas o que a mudança de código torna errado ou incompleto. Não reescreva seções não relacionadas. Para redação clara, use a skill simple-english se estiver instalada.
6. Commite junto. Prepare as alterações de documento junto com o código. Não as coloque em um PR posterior.
7. Relate. Liste os documentos que você alterou. Se nenhum precisou de alteração, diga isso em uma linha e dê o motivo. Por exemplo: "Sem docs: refatoração interna, sem mudança no comportamento, comandos ou configurações."

Quando o dono não está claro

Pergunte ao usuário. Não crie um novo documento para evitar a pergunta.

Um teste útil: é um fato sobre o estado atual (uma configuração, uma versão, um status)? Vai no documento de referência ou status. É um procedimento (passos que alguém segue)? Vai no guia, runbook ou skill que é dona desse procedimento.

Especificações vêm primeiro

Se o repositório tem um SPEC.md (veja engineering:spec-writing) ou especificações gener8v sob .gener8v/specifications/, elas definem o comportamento pretendido.

• Se sua alteração faz o que a especificação diz, a especificação não precisa de edição.
• Se sua alteração contradiz a especificação, pare. Informe o usuário. Altere a especificação primeiro, através de seu dono: engineering:spec-writing para SPEC.md, gener8v:specification para especificações de pipeline. Não edite a especificação silenciosamente para coincidir com o código.

Documentos de pipeline

Não edite arquivos sob .gener8v/ manualmente. As skills de pipeline gener8v escrevem e atualizam-nos.

Skills relacionadas

• engineering:documentation-bootstrap: quando um documento inteiro está faltando, não apenas um parágrafo.
• engineering:github-pr-merge: executa esta verificação antes de um PR.
• engineering:github-release: lê a seção Unreleased do CHANGELOG que esta skill mantém atualizada.