akshaysanthosh/docs-drift-check

Verificação de Desvio de Documentação

Determina se um branch ou diff provavelmente criou desvio de documentação e aponta exatamente quais arquivos de documentação e termos merecem revisão. Este skill deve priorizar evidências concretas do diff, não especulações amplas.

Use Este Skill Quando

• O usuário pergunta se um branch, PR ou alteração local provavelmente precisa de atualizações na documentação.
• O diff altera comportamento voltado ao público, como rotas de API, flags de CLI, variáveis de ambiente, chaves de configuração, etapas de configuração ou nomes de arquivos/módulos que a documentação pode referenciar.
• A tarefa é revisar README, docs/, examples/, documentação de onboarding ou configuração em busca de desvios.

Não use este skill para alterações puramente estilísticas, alterações apenas de testes ou refatorações claramente internas sem mudança visível de comportamento.

Início Rápido

1. Execute o helper: bash .agents/skills/docs-drift-check/scripts/docs_drift_check.sh [base-ref]
2. Leia as seções de maior sinal primeiro:
   • Possíveis renomeações
   • Possíveis alterações em variáveis de ambiente
   • Possíveis alterações em flags de CLI
   • Possíveis alterações em rotas ou endpoints
   • Possíveis alterações de configuração
3. Inspecione os alvos mais prováveis de documentação:
   • README.md
   • docs/
   • examples/
   • documentação de configuração ou onboarding próxima ao recurso afetado
4. Retorne um resultado curto com:
   • nível de risco: baixo, médio ou alto
   • evidências concretas do diff
   • arquivos de documentação provavelmente impactados
   • edições recomendadas ou plano de patch

Fluxo de Trabalho

1. Estabeleça a comparação

• Prefira um base-ref fornecido pelo usuário.
• Se nenhum for fornecido, o helper usa como padrão main.
• Se o base-ref estiver ausente, informe claramente e peça o branch correto ou alvo de comparação.

2. Identifique mudanças sensíveis à documentação

Concentre-se em tipos de mudança de alto sinal:

• variáveis de ambiente
• flags e comandos de CLI
• rotas ou endpoints de API
• chaves de configuração
• arquivos ou módulos renomeados
• passos de configuração ou onboarding

Use o script helper para uma primeira passagem determinística, depois inspecione o diff manualmente se necessário.

3. Compare as alterações de código com a documentação

• Procure na documentação por nomes antigos e novos, caminhos, flags, rotas e termos de configuração.
• Prefira a documentação mais próxima da área alterada antes de escanear o repositório inteiro.
• Leia references/heuristics.md quando precisar da rubrica de sinal ou formato de saída.

4. Classifique o resultado

• baixo: documentação provavelmente OK, ou apenas sinais fracos sem referências desatualizadas encontradas
• médio: possível desvio, ou mudanças fortes na superfície pública sem documentação desatualizada confirmada
• alto: desvio provável ou confirmado com termos, caminhos ou instruções desatualizados específicos

5. Mantenha a saída concisa

Use este formato:

1. Nível de risco
2. Por quê
3. Arquivos de documentação impactados
4. Edições recomendadas

Regras

• Prefira evidências determinísticas do diff antes de palpites semânticos.
• Não afirme desvio confirmado a menos que possa apontar uma referência desatualizada concreta, uma atualização de documentação ausente ou um caminho renomeado.
• Se a evidência for parcial, diga possível desvio em vez de exagerar a certeza.
• Ignore alterações apenas de formatação, apenas de comentários e apenas de testes, a menos que alterem o comportamento voltado ao usuário.
• Mantenha o resultado curto e acionável.