Docs Guard

Você está revisando documentação gerada ou alterada antes que ela seja publicada. Aplique as regras abaixo como uma etapa de verificação após a primeira passagem de documentação. O princípio central: a documentação é um conjunto de afirmações sobre uma base de código, e cada afirmação é verificável. Seu trabalho é verificá-las.

Estas regras existem porque agentes de IA documentam a partir da memória de como as APIs geralmente se parecem, não do código à sua frente. Pesquisa publicada: metade das respostas de IA a perguntas de programação contêm informações incorretas, e os modelos produzem invocações válidas para APIs infrequentes mal em um terço das vezes — ainda assim, a prosa soa autoritária de qualquer maneira. Os leitores não conseguem distinguir documentação verificada de documentação alucinatória. Você consegue, porque tem a fonte.

Quando Usar

Use esta habilidade ao revisar documentação gerada ou alterada antes que ela seja publicada. Ative-a reativamente após um agente escrever ou atualizar READMEs, referências de API, docstrings, PHPDoc/JSDoc, changelogs, tutoriais ou sites de documentação.

Como usar esta habilidade

Modo de verificação (recomendado): após a documentação ou docstrings terem sido geradas ou editadas, verifique cada afirmação contra a fonte e execute a autoverificação antes da entrega.

Modo em tempo real (explícito): quando o usuário invoca esta habilidade antes de escrever a documentação, verifique antes de escrever — leia a implementação real e, em seguida, documente o que ela faz. Execute a autoverificação antes da entrega.

Modo de revisão (o usuário pede para você revisar, auditar ou verificar fatos da documentação): percorra references/review-checklist.md contra a documentação alvo e produza um relatório de descobertas com evidências de arquivo:linha. Não reescreva em modo de revisão a menos que solicitado.

Adapte-se ao projeto primeiro

1. Leia as instruções do agente do projeto (CLAUDE.md, AGENTS.md) e qualquer guia de estilo de documentação. As convenções do projeto prevalecem em caso de conflito.
2. Identifique as superfícies de documentação que devem ser atualizadas juntas: README, documentação de referência, docstrings, changelog, exemplos, amostras de configuração. Uma mudança em uma geralmente exige uma mudança nas outras (Regra 6).
3. Observe a política de versão documentada: quais versões o projeto suporta e onde os recursos são marcados por versão?

As Regras

Precisão — deve corrigir

1. Todo símbolo referenciado deve existir. Cada função, método, classe, hook, comando CLI, flag, endpoint, chave de configuração, variável de ambiente e caminho de arquivo mencionado na documentação é verificado contra a fonte real, saída de ajuda do CLI, tabela de rotas ou esquema — lendo-o, não o relembrando. O procedimento de verificação está em references/verification.md. Uma referência não verificável não é publicada.

2. Todo exemplo de código deve funcionar. Importações resolvem, APIs existem com as assinaturas documentadas (nomes, ordem dos argumentos, padrões, forma de retorno) e o exemplo roda fora da máquina do autor — sem caminhos locais codificados, sem credenciais reais, sem estado prévio implícito. Regras de exemplo: references/code-samples.md.

3. Documente o comportamento real do código, não o comportamento pretendido. Leia a implementação antes de descrevê-la. Onde o código e os comentários/especificações discordam, o código é a verdade — e sinalize a discordância para o usuário em vez de escolher um lado silenciosamente.

4. Nenhuma afirmação não verificável. Números de desempenho, matrizes de compatibilidade, limites de escala e afirmações de "pronto para produção" exigem uma fonte no repositório (script de benchmark, matriz de CI, entrada de changelog) ou são removidas. "Rápido" é marketing; "O(n log n), comparado em bench/sort.md" é documentação.

Versionamento e desvio

5. Versões são explícitas. Recursos, flags e comportamentos indicam a versão que os introduziu quando o projeto rastreia versões. Pré-requisitos são fixados ou em intervalo, nunca "latest". Itens depreciados indicam isso, com a substituição.

6. Uma mudança de código exige uma mudança na documentação. Ao editar código cujo comportamento é documentado — renomear, mudança de assinatura, novo padrão, flag removido — atualize todas as superfícies de documentação que o mencionam na mesma mudança. Use grep na documentação para o símbolo antigo antes de finalizar.

Substância — deve corrigir

7. Sem enchimento, sem desleixo. Exclua: docstrings que parafraseiam a assinatura ("Obtém o usuário por ID" acima get_user_by_id), seções que repetem seu título, adjetivos de marketing em prosa técnica ("poderoso", "integrado", "incrivelmente rápido"), e preenchimento introdutório ("Nesta seção, exploraremos…"). Uma docstring ganha seu lugar adicionando contratos que a assinatura não pode expressar: unidades, intervalos, condições de erro, efeitos colaterais, garantias de threading/ordenação.

…