Sincronizar docs
A documentação deriva silenciosamente. Nada falha quando um README nomeia um arquivo que foi movido. Execute esta skill após cada etapa de PR empilhado ou funcionalidade concluída, antes de abrir o PR.
O contrato desta skill inclui commits. Ela pode fazer commit sem perguntar, sempre na branch atual, nunca main.
Quando pular
- Nada que um documento referencie mudou (lógica interna pura). Ainda assim, escreva "docs verificados, sem deriva" na seção de Testes do PR, para que o revisor saiba que foi executado.
- O usuário explicitamente não quer um commit de documentação ainda.
O inventário: docs/DOCS.md
A lista de documentos no escopo fica em docs/DOCS.md, não em AGENTS.md, para que o contexto sempre ativo não cresça a cada sincronização.
# Inventário de docs
| Caminho | Possui | Gerado por |
|---|---|---|
| README.md | Pitch, configuração, env vars, layout | |
| AGENTS.md | Regras do agente + portões do projeto | |
| packages/api/README.md | Endpoints, scripts, env vars | |
| docs/api/openapi.json | Referência da API | `pnpm generate:openapi` |
## Congelado (nunca editado por uma sincronização)
- docs/plans/
## Verificações de deriva
<!-- um grep por erro que já aconteceu, com um comentário explicando o porquê -->
Primeira execução: construa-o. Varra por README.md / AGENTS.md / CLAUDE.md na raiz e por pacote, documentos do contribuidor, docs de API (descrições OpenAPI, llms.txt), diretórios de skills e regras, e referências a variáveis de ambiente (.env.example, schemas de configuração). Anote o que cada um possui.
Toda execução: um documento que você encontrar e que não estiver listado será adicionado, no mesmo commit.
Procedimento
- Auditar. Diferencie a branch em relação à sua base (
git diff <base>...HEAD --stat) e liste o que mudou que um documento poderia mencionar: caminhos, nomes de pacotes, rotas, comandos e scripts, env vars, APIs exportadas, comportamento, convenções. - Verificar. Para cada documento no inventário, verifique cada alegação concreta em relação ao código: cada arquivo nomeado existe naquele caminho, cada comando existe no manifesto, cada env var é realmente lida, cada rota e exportação existe conforme descrito. Leia o código; não confie na prosa, incluindo prosa que você escreveu antes.
- Editar. Corrija a deriva. Descreva o que o código faz e nunca invente comportamento para fazer um documento parecer melhor. Se o código e o documento discordarem e você não souber qual está errado, sinalize-o em vez de adivinhar.
- Regenerar. Execute cada comando gerador listado no inventário. Nunca edite manualmente um documento gerado.
- Executar as verificações de deriva listadas em
docs/DOCS.md. Quando uma sincronização encontrar um erro que provavelmente se repetirá (um caminho antigo, um comando renomeado), adicione um grep para ele com um comentário explicando o porquê. - Comitar. Prepare os arquivos por caminho, nunca
git add -A. Faça um commit atômico,docs(<escopo>): sincronizar <o que> com <mudança>, na branch atual. - Enviar se a branch já rastreia um remoto (
git pull --rebaseprimeiro). Nunca envie paramain.
Regras
- Histórico congelado: designs, planos e transferências em
docs/plans/são instantâneos do que foi decidido na época. Eles aparecerão em greps; isso é esperado, não é deriva. Nunca os edite em uma sincronização. - Protótipos e spikes são excluídos uma vez que sua direção é enviada ou descartada, não mantidos como referência. As conclusões de um spike são o texto menos confiável no repositório assim que a produção sabe mais. Qualquer coisa que ainda valha a pena saber é movida para a documentação do código enviado.
- Orçamento de tamanho: linhas de documentação contam para o orçamento do PR. Se a sincronização empurrar uma etapa além de 500 linhas, finalize-a como uma etapa apenas de documentação no topo da pilha (veja
stacked-prs). - Arquivos de ponteiro permanecem pequenos. Um
CLAUDE.mdouGEMINI.mdque apenas aponta paraAGENTS.mddeve permanecer assim. Não copie conteúdo para ele.