yha9806/academic-writing-toolkit

/audit — Habilidade de Auditoria de Consistência de Tese

Propósito

Examinar todos os capítulos da tese em busca de problemas de consistência interna de dados: números contraditórios, terminologia inconsistente, referências cruzadas quebradas e erros aritméticos. Esta é uma verificação de qualidade pré-submissão.

Palavras de Ativação

Esta habilidade é ativada por: audit, consistency check, check numbers, /audit.

Fluxo de Trabalho

1. Examinar todos os arquivos de capítulo no diretório chapters/ usando Glob. Ler cada arquivo para extrair afirmações quantitativas, terminologia e referências cruzadas.

2. Verificar as seguintes categorias:

   A. Consistência numérica

   • A mesma estatística (ex.: precisão, tamanho da amostra, valor-p) citada em vários capítulos deve ter o mesmo valor.
   • Percentuais em uma distribuição devem somar 100% (com tolerância de +/-1% para arredondamento).
   • Contagens (ex.: "42 modelos") devem coincidir entre os capítulos.

   B. Consistência terminológica

   • O mesmo conceito deve usar o mesmo termo em todo o texto. Sinalizar casos em que sinônimos são usados inconsistentemente (ex.: "pseudo-entendimento" vs. "compreensão falsa" para o mesmo conceito).
   • Abreviações devem ser definidas na primeira utilização em cada capítulo.

   C. Validade das referências cruzadas

   • Referências a outras seções (ex.: "como discutido na Seção 3.2") devem apontar para seções que existem.
   • Referências a tabelas e figuras devem corresponder aos números reais de tabelas/figuras.
   • Referências futuras ("O Capítulo 6 mostrará...") devem ser cumpridas.

   D. Consistência das citações

   Executar python3 scripts/audit-citations.py --base-dir . --style $(grep -oP '(?<=Citation style: )\S+' CLAUDE.md) --json e analisar a saída JSON. O script implementa quatro níveis:

   • Nível 0 — Verificação de linhas de origem nos arquivos literature/reading_notes/*_NOTES.md. Sinaliza linhas **Source**: ausentes ou mal formatadas. Severidade medium (notes-source-missing) ou medium (notes-source-malformed).
   • Nível 1 — Pareamento. Cada citação no texto deve corresponder a uma entrada **Source**:; cada Fonte deve ser citada pelo menos uma vez. Três modos:
     • Autor-Ano (Harvard, APA, Chicago Autor-Data, GB/T 7714-2015): parear por (sobrenome, ano). Fantasmas e não utilizados → severidade high.
     • Autor-Página (MLA): parear apenas por sobrenome.
     • Numérico (IEEE, Vancouver): parear por equilíbrio de contagem + detecção de lacunas inteiras.
   • Nível 2 — Detecção de modo de estilo em todas as citações no texto. Sinaliza discrepâncias quando o manuscrito oscila (ex.: (Smith 2024) e (Smith, 2024) misturados). Severidade medium.
   • Nível 3 — Validação de formatação por estilo contra o Citation style: declarado em CLAUDE.md. Sinaliza violações de vírgula errada, limite de et al., conector multi-autor errado. Severidade low.

   O código de saída do script é 0 (sem problemas), 1 (problemas em qualquer nível) ou 2 (argumentos inválidos). Adicionar os problemas do script à tabela Issues abaixo como novas linhas; o vocabulário de severidade mapeia diretamente (critical | high | medium | low | info).

   Ver docs/superpowers/specs/2026-04-27-c-rest-citation-design.md para o esquema JSON e o registro de estilos suportados.

3. Gerar o relatório de auditoria usando o formato abaixo.

Formato de Saída

## Relatório de Auditoria -- {AAAA-MM-DD}

### Resumo

- **Crítico**: {N} problemas (dados contraditórios)
- **Alto**: {N} problemas (referências quebradas, definições ausentes)
- **Médio**: {N} problemas (inconsistência terminológica, pequenos erros aritméticos)

### Problemas

| # | Severidade | Categoria | Localização | Problema | Atual | Esperado |
|---|------------|-----------|-------------|---------|-------|----------|
| 1 | Crítico | Numérico | Cap3 s3.2, Cap5 s5.4 | Valor PUR difere | 22,5% (Cap3) vs 23,1% (Cap5) | Deve ser consistente |
| 2 | Alto | Ref. cruzada | Cap4 s4.1 | Ref. para "Seção 3.7" | Seção 3.7 | Seção não existe |

### Recomendações

{Agrupadas por severidade, breves notas sobre como resolver cada problema.}

Níveis de Severidade

• Crítico: A mesma afirmação quantitativa tem valores diferentes em capítulos diferentes. Isso compromete diretamente a credibilidade da tese.
• Alto: Referências cruzadas quebradas, abreviações não definidas no primeiro uso, números de tabela/figura ausentes.
• Médio: Terminologia inconsistente que não causa erro factual, pequenas discrepâncias de arredondamento dentro da tolerância.

Restrições

1. Nunca corrigir automaticamente. Listar todos os problemas para o usuário revisar e decidir. O usuário pode optar por corrigir seletivamente.
2. Sem emoji na saída.
3. Relatar todas as ocorrências, não apenas a primeira. Se uma estatística aparecer em 4 capítulos com 2 valores diferentes, listar todas as 4 localizações.
4. Ser específico sobre as localizações. Fornecer número do capítulo, número da seção e contexto ao redor para que o usuário possa encontrar o problema rapidamente.
5. Não sinalizar problemas estilísticos. Esta habilidade verifica consistência de dados, não qualidade da prosa.