Validador de Consistência de Conteúdo
Visão Geral
Verifica o conteúdo quanto à consistência de tom, terminologia, formatação e estrutura em múltiplas fontes de documentação (sites, repositórios GitHub, documentos locais). Gera relatórios de discrepância somente leitura com descobertas classificadas por gravidade e sugestões de correção acionáveis, incluindo caminhos de arquivo e números de linha.
Exemplos
- Auditoria pré-lançamento: Antes de marcar uma nova versão, execute o validador para capturar incompatibilidades de versão entre seu README, site de documentação e changelog — por exemplo, o site diz v2.1.0, mas o README do GitHub ainda referencia v2.0.0.
- Verificação pós-rebranding: Após renomear um produto ou atualizar a terminologia (ex.: "plugin" para "extensão"), valide se toda a documentação, páginas de destino e guias de contribuição usam o novo termo de forma consistente.
- Revisão de onboarding: Quando um novo colaborador sinalizar documentação confusa, execute uma verificação de consistência para revelar alegações contraditórias de recursos, informações de contato desatualizadas ou seções ausentes em suas fontes de documentação.
Pré-requisitos
- Acesso a pelo menos duas fontes de conteúdo (site, repositório GitHub ou diretório de documentos locais)
- Permissões WebFetch configuradas para URLs remotas (sites implantados, conteúdo raw do GitHub)
- Documentação local armazenada em caminhos reconhecíveis (
docs/,claudes-docs/,internal/)
Instruções
- Descobrir fontes — vasculhe diretórios de build (
dist/,build/,public/,out/,_site/), arquivos README/CONTRIBUTING do GitHub e pastas de documentos locais:find . -maxdepth 3 -name "README*" -o -name "CONTRIBUTING*" | head -20 ls -d docs/ claudes-docs/ internal/ 2>/dev/null - Extrair dados estruturados de cada fonte: números de versão, alegações de recursos, nomes de produtos, slogans, informações de contato, URLs e requisitos técnicos:
grep -rn 'v[0-9]\+\.[0-9]\+' docs/ README.md grep -rn -i 'features\|capabilities' docs/ README.md - Verificar extração — confirme pelo menos 3 pontos de dados por fonte. Se uma fonte retornar vazia, consulte a tabela de Tratamento de Erros antes de continuar.
- Construir matriz de comparação emparelhando cada fonte contra todas as outras (site vs GitHub, site vs documentos locais, GitHub vs documentos locais):
diff <(grep -i 'version' README.md) <(grep -i 'version' docs/overview.md) - Classificar discrepâncias por gravidade:
- Crítico: números de versão conflitantes, listas de recursos contraditórias, informações de contato incompatíveis, referências cruzadas quebradas
- Aviso: terminologia inconsistente (ex.: "plugin" vs "extensão"), informações ausentes em uma fonte, datas desatualizadas
- Informativo: diferenças estilísticas, redação específica da plataforma, níveis de detalhes divergentes
- Aplicar prioridade de confiança: site (mais autoritativo) > GitHub (voltado para desenvolvedores) > documentos locais (uso interno).
- Gerar relatório em Markdown com: resumo executivo, tabelas de comparação por par, matriz de consistência terminológica e itens de ação priorizados com caminhos de arquivo e números de linha.
- Salvar em
consistency-reports/YYYY-MM-DD-HH-MM-SS.md.
Formato do Relatório
# Relatório de Consistência — YYYY-MM-DD
## Resumo Executivo
| Gravidade | Contagem |
|-----------|----------|
| Crítico | 2 |
| Aviso | 5 |
| Info | 3 |
## Site vs GitHub
| Campo | Site | GitHub | Gravidade |
|------------|---------------|---------------|-----------|
| Versão | v2.1.0 | v2.0.0 | Crítico |
| Recurso X | listado | ausente | Aviso |
## Itens de Ação
1. **Crítico** — Atualizar `README.md:14` versão de v2.0.0 → v2.1.0
2. **Aviso** — Adicionar "Recurso X" à lista de recursos do `README.md`
Tratamento de Erros
| Erro | Causa | Solução |
|---|---|---|
| Conteúdo do site inacessível | URL retorna 4xx/5xx ou diretório de build ausente | Verifique se o site está implantado ou execute build local; verifique permissões WebFetch |
| Limite de taxa da API do GitHub | Muitas requisições em janela curta | Pause e tente novamente após o reset da janela; use requisições autenticadas |
| Nenhum diretório de documentação | Caminhos esperados não existem | Confirme o diretório de trabalho; especifique o caminho da documentação explicitamente |
| Extração de conteúdo vazia | Renderização do lado do cliente não visível para fetch | Use diretório de saída do build local em vez da URL ativa |
| Falha no comando diff | Caminhos de arquivo contêm caracteres especiais | Coloque todos os caminhos de arquivo passados para diff e grep entre aspas |
Recursos
- Lógica de descoberta de fontes de conteúdo:
${CLAUDE_SKILL_DIR}/references/how-it-works.md - Prioridade de confiança e tempo de validação:
${CLAUDE_SKILL_DIR}/references/best-practices.md - Tutoriais de caso de uso:
${CLAUDE_SKILL_DIR}/references/example-use-cases.md