FlorianBruniaux/claude-code-ultimate-guide

source-command-audit-whitepapers

Use esta skill quando o usuário solicitar a execução do comando migrado audit-whitepapers.

Template de Comando

Auditoria de Whitepapers & Recap Cards

Auditoria abrangente de atualização e qualidade para todos os whitepapers (FR + EN) e recap cards (FR + EN). Pontua cada documento em relação à versão atual do guia, verifica a paridade FR/EN e valida a consistência dos metadados.

Argumentos

• --fix - Gera sugestões de atualização e patches de frontmatter (não modifica arquivos)
• --verbose - Mostra todos os critérios, incluindo os aprovados, não apenas as falhas
• --cards-only - Audita apenas recap cards (pula whitepapers principais)
• --wp-only - Audita apenas whitepapers principais (pula recap cards)

Uso

/audit-whitepapers                  # Auditoria completa, apenas falhas
/audit-whitepapers --fix            # Auditoria + sugestões de atualização priorizadas
/audit-whitepapers --verbose        # Detalhes completos para todos os critérios
/audit-whitepapers --cards-only     # Apenas recap cards
/audit-whitepapers --wp-only        # Apenas whitepapers

---

Fase 1: Descoberta

Objetivo: Localizar e inventariar todos os documentos auditáveis.

Etapas

1. Ler a versão atual do guia: Leia o arquivo VERSION na raiz do projeto. Esta é a versão alvo com a qual todos os documentos devem estar sincronizados.

2. Escaneie diretórios em busca de arquivos .qmd:

   whitepapers/fr/         (whitepapers principais FR)
   whitepapers/en/         (whitepapers principais EN)
   whitepapers/recap-cards/fr/    (recap cards FR)
   whitepapers/recap-cards/en/    (recap cards EN)
   

3. Classifique cada arquivo:

   • Whitepaper principal: arquivos que correspondem a [0-9][0-9]-*.qmd em whitepapers/fr/ ou whitepapers/en/
   • Cheatsheet: arquivos que correspondem a *cheatsheet*.qmd (rastreados separadamente, não pontuados)
   • Whitepaper personalizado: arquivos que correspondem a *-whitepaper.qmd ou *-cheatsheet.qmd de parceiros externos (strangebee, purchasely, devwithai) -- excluídos da pontuação, listados separadamente
   • Recap card: todos os arquivos .qmd em recap-cards/fr/ ou recap-cards/en/
   • Bundle/include: fiches-recap-serie.qmd, arquivos no subdiretório fiches/ -- excluídos (são documentos compostos)

4. Analise o frontmatter YAML de cada arquivo incluído (leia entre o primeiro --- e o segundo ---). Extraia:

   • title, subtitle, author, date
   • version (versão do guia rastreada em WPs principais e recap cards)
   • wp-version (semver próprio do whitepaper, apenas WPs principais)
   • guide-version (campo de versão explícita do guia usado em recap cards)
   • card-number, category, difficulty (apenas recap cards)
   • series (apenas WPs principais)

5. Exiba o resumo da descoberta:

   Versão do guia: {VERSION}
   Encontrados: {N} whitepapers principais ({FR}/{EN} FR/EN), {N} recap cards ({FR}/{EN} FR/EN)
   Excluídos: {N} arquivos personalizados (strangebee, purchasely, devwithai), {N} arquivos bundle
   

---

Fase 2: Análise de Lacuna de Versão (40 pontos por arquivo)

Objetivo: Pontuar o quão atualizado cada documento está em relação ao guia.

Lógica de comparação Semver

Analise as strings de versão como MAJOR.MINOR.PATCH. A métrica de desatualização é lacuna_menor = menor_atual - menor_arquivo (usando o mesmo MAJOR). Se o MAJOR for diferente, trate como crítico.

Para whitepapers principais, o campo de versão do guia é version. Para recap cards, o campo de versão do guia é guide-version (recorre a version se ausente).

Tabela de pontuação

Critério	Pontos	Detecção
Versão do guia atual (0-1 menor atrasada)	15	lacuna_menor <= 1
Versão do guia recente (2-3 menor atrasada)	10	lacuna_menor 2-3 (crédito parcial, substitui os 15)
Versão do guia antiga (4-10 menor atrasada)	5	lacuna_menor 4-10 (crédito parcial)
Campo wp-version presente e semver válido	5	Campo existe E corresponde a \d+\.\d+\.\d+ (apenas WP)
wp-version consistente com o par FR/EN	10	Mesmo valor de wp-version no arquivo correspondente (apenas WP)
guide-version consistente com o par FR/EN	10	Mesmo guide-version (ou version) no correspondente (cards)

Rótulos de atualização:

• 0-1 menor atrasada: Atualizado
• 2-3 menor atrasada: Desatualizado
• 4-10 menor atrasada: Muito Desatualizado
• 11+ menor atrasada: Crítico

Nota: Os 15, 10, 5 pts para versão do guia são mutuamente exclusivos (conceda apenas o nível mais alto aplicável).

---

Fase 3: Verificação de Conteúdo Desatualizado (20 pontos por arquivo)

Objetivo: Detectar se as seções do guia que um whitepaper cobre foram alteradas desde sua última atualização.

Mapeamento Whitepaper-para-Guia (incorporado)

WP#	Prefixo FR	Prefixo EN	Seções do Guia
00	00-introduction	00-series-introduction	guide/ultimate-guide.md Cap.1-2
01	01-prompts	01-effective-prompts	Cap.2 seções de prompting
02	02-personnalisation	02-customization	Cap.3 Memória, Cap.4 Agentes, Cap.5 Skills
03	03-securite	03-security	Cap.7 Hooks, seções de segurança
04	04-architecture	04-architecture	Cap.2 aspectos internos, seções de arquitetura
05	05-equipe	05-team	Cap.3 configuração de equipe, Cap.9 CI/CD
06	06-privacy	06-privacy	Cap.2 seções de dados/privacidade
07	07-guide-reference	07-reference-guide	Cap.10 Referência
08	08-agent-teams	08-agent-teams	Cap.9 equipes de agentes
09	09-apprendre	09-learning	guide/roles/learning-with-ai.md
10	10-budget	10-ai-budget	Conteúdo de Negócios/ROI

Etapas

1. Para cada whitepaper principal, extraia o campo date. Se a data não estiver no formato YYYY-MM-DD, analise-a (por exemplo, "2026-02-12" ou "Março 2026").
2. Execute git log --since="{data}" --oneline -- guide/ultimate-guide.md guide/roles/ guide/core/ para contar os commits que tocaram no conteúdo do guia desde a data do whitepaper.
3. Pontue:

Critério	Pontos	Detecção
Nenhum commit do guia desde a data do WP	10	git log retorna 0 commits
Poucos commits desde a data do WP (1-5)	7	1-5 commits (parcial)
Commits moderados (6-15)	4	6-15 commits (parcial)
Muitos commits (>15)	0	Mais de 15 commits
Mapeamento definido para este WP	5	O número do WP está na tabela de mapeamento acima
Histórico do Git acessível	5	O comando git log é executado sem erros

Recap cards: Pule a análise detalhada do git. Atribua uma pontuação de desatualização fixa com base em lacuna_menor:

• 0-1 atrasado: 20 pts
• 2-3 atrasado: 15 pts
• 4-10 atrasado: 8 pts
• 11+ atrasado: 0 pts

---

Fase 4: Verificação de Paridade FR/EN (20 pontos por arquivo)

Objetivo: Cada documento deve ter uma contraparte completa e com versão consistente no outro idioma.

Estratégia de emparelhamento

Whitepapers principais: Correspondência pelo prefixo numérico de dois dígitos (por exemplo, 00, 03, 10). Os nomes de arquivos FR e EN diferem, mas o prefixo é consistente.

Recap cards: Correspondência pelo nome de arquivo idêntico (ambos os diretórios de idioma usam os mesmos nomes de arquivo).

Tabela de pontuação

Critério	Pontos	Detecção
Arquivo correspondente existe no outro idioma	10	Encontrado arquivo com prefixo correspondente (WP) ou nome idêntico (cards)
wp-version corresponde entre pares	5	Mesmo valor de wp-version (apenas WP)
Versão do guia corresponde entre pares	5	Mesmo valor de version/guide-version

Pontue tanto os arquivos FR quanto EN de um par de forma idêntica na paridade (se o par estiver completo, ambos recebem 20; se um estiver faltando, o arquivo existente pontua 0 em paridade).

---

Fase 5: Qualidade dos Metadados (20 pontos por arquivo)

Objetivo: Validar a completude do frontmatter, formatos dos campos e consistência entre arquivos do mesmo tipo.

Whitepapers principais (máx. 20 pontos)

Critério	Pontos	Detecção
Campos obrigatórios presentes	6	Possui todos: title, subtitle, author, date, version, wp-version, series
version segue padrão semver	3	Corresponde a \d+\.\d+\.\d+
wp-version segue padrão semver	3	Corresponde a \d+\.\d+\.\d+
date é analisável e não está no futuro	3	Data válida, não posterior a hoje
Valor de series é consistente	2	É igual a "Codex Ultimate Guide"
Nenhum wp-version ausente (não deixado vazio ou ausente)	3	Campo possui um valor não vazio

Recap cards (máx. 20 pontos)

Critério	Pontos	Detecção
Campos obrigatórios presentes	5	Possui todos: title, subtitle, card-number, category, difficulty, guide-version, author, version, date
card-number corresponde ao prefixo do nome do arquivo	4	Ex.: C01 em card-number corresponde a c01- no nome do arquivo
category válido para o idioma	4	FR: um de "Technique", "Methodologie", "Conception"; EN: um de "Technical", "Methodology", "Design" (sinalize "Conceptual" como inconsistente em EN)
difficulty é um valor válido	3	Um de: "beginner", "intermediate", "advanced"
guide-version e campos version correspondem entre si	4	Ambos os campos existem e têm o mesmo valor dentro do mesmo arquivo

Problema conhecido para detectar automaticamente: Os cards da série C em EN usam dois valores de categoria diferentes ("Conceptual" em c01-c05, "Design" em c06+). Sinalize essa inconsistência explicitamente na seção de Problemas de Metadados do relatório.

---

Fase 6: Pontuação e Classificação

Fórmula de pontuação (por arquivo)

Total = Lacuna de Versão (40) + Conteúdo Desatualizado (20) + Paridade FR/EN (20) + Qualidade dos Metadados (20)
Pontuação = (Total / 100) * 100  [como porcentagem]

Escala de notas

Nota	Pontuação	Status
A	90-100	Atualizado, totalmente sincronizado
B	80-89	Bom (limiar de produção)
C	70-79	Precisa de atualização em breve
D	60-69	Desatualizado, deve priorizar
F	<60	Crítico: conteúdo provavelmente desatualizado

Pontuação geral de saúde

Saúde Ponderada = (Soma das pontuações dos WPs * 2 + Soma das pontuações dos cards * 1) / (Contagem de WPs * 2 + Contagem de cards * 1)

Whitepapers são ponderados 2x porque têm 20-80 páginas cada, vs. recap cards de 2 páginas. Um whitepaper desatualizado carrega mais risco.

---

Fase 7: Relatório

Gere o seguinte relatório em Markdown. Use blocos <details> para detalhamentos individuais de arquivos, a fim de manter o nível superior escaneável.

# Auditoria de Whitepaper & Recap Card

**Data**: {hoje}
**Versão do Guia**: {VERSION}
**Saúde Geral**: {pontuação}% ({nota})
**Arquivos Auditados**: {total} ({contagem_wp} whitepapers, {contagem_card} recap cards)

---

## Painel de Status da Versão

| Status | Whitepapers | Recap Cards | Total |
|--------|-------------|-------------|-------|
| Atualizado (0-1 menor atrasado)   | N | N | N |
| Desatualizado (2-3 menor atrasado)   | N | N | N |
| Muito Desatualizado (4-10 atrasado)   | N | N | N |
| Crítico (11+ atrasado)      | N | N | N |

**Versões atualmente em uso**:
- WP Principal 00-09: {versão} ({lacuna} versões menores atrasadas)
- WP Principal 10: {versão} ({lacuna} versões menores atrasadas)
- Recap cards: {guide-version} ({lacuna} versões menores atrasadas)

---

## Pontuações dos Whitepapers

| WP# | Título | version | Lacuna | wp-version | Paridade | Pontuação | Nota |
|-----|-------|---------|-----|------------|--------|-------|-------|
| 00  | ...   | ...     | -N  | ...        | OK/lacuna | N%    | X     |
...

<details>
<summary>Detalhamento individual de critérios (WP 00)</summary>

| Fase | Critério | Resultado | Pontos |
|-------|-----------|--------|--------|
| Lacuna de Versão | Versão do guia atual | Crítico (-11) | 0/15 |
| Lacuna de Versão | wp-version semver válido | OK | 5/5 |
| ... | ... | ... | ... |
| **Total** | | | **N/100** |
</details>

---

## Pontuações dos Recap Cards

| Série | Cards | Média guide-version | Média Lacuna | Média Pontuação | Nota |
|--------|-------|-------------------|---------|-----------|-------|
| T (Technical)    | 22 | ... | -N | N% | X |
| M (Methodology)  | 22 | ... | -N | N% | X |
| C (Conceptual)   | 13 | ... | -N | N% | X |

<details>
<summary>Pontuações individuais dos cards</summary>

| Card | Categoria | guide-version | Lacuna | Paridade | Metadados | Pontuação | Nota |
|------|----------|---------------|-----|--------|----------|-------|-------|
...
</details>

---

## Relatório de Paridade FR/EN

### Whitepapers
| WP# | FR | EN | Correspondência wp-version | Correspondência version |
|-----|----|----|------------------|---------------|
...

### Recap Cards
- **Contagem FR**: {N} | **Contagem EN**: {N}
- **FR ausentes**: [lista ou "Nenhum"]
- **EN ausentes**: [lista ou "Nenhum"]
- **Incompatibilidades de versão**: [lista ou "Nenhum"]

---

## Problemas de Metadados

### Conhecido: Inconsistência de Categoria em Recap Cards EN
Os cards da série C em EN usam dois valores diferentes para a categoria "Conceptual/Design":
- "Conceptual": c01, c02, c03, c04, c05
- "Design": c06, c07, c08, ...
Recomendação: padronizar para "Design" para corresponder à terminologia do guia.
Arquivos afetados: whitepapers/recap-cards/en/c01-*.qmd até c05-*.qmd (alterar "Conceptual" para "Design")

### Outros problemas
[Liste quaisquer campos ausentes, formatos incorretos, problemas de data...]

---

## Itens de Ação Priorizados

### Crítico (Nota F, 11+ versões atrasadas)
[Liste whitepapers específicos com caminhos de arquivo]

### Alto (Nota D-F, 2+ versões atrasadas)
[Liste arquivos específicos]

### Médio (Qualidade dos metadados, correções de categoria)
[Liste problemas específicos]

### Baixo (Polimento, alinhamento de datas)
[Liste problemas específicos]

---

## Próximos Passos

1. Execute `/update-whitepapers --since {versão_mais_antiga}` para atualizar todos os WPs desatualizados
2. Corrija a inconsistência de categoria EN (5 arquivos: c01 a c05, altere "Conceptual" para "Design")
3. Reexecute `/audit-whitepapers` após as atualizações para acompanhar o progresso
4. Meta: 80%+ de saúde (Nota B) em todos os arquivos

---

Modo de Correção (--fix)

Quando --fix for passado, anexe uma seção de Sugestões de Correção após o relatório. Esta seção fornece patches concretos, mas NÃO modifica nenhum arquivo.

Patches de versão do frontmatter

Para cada arquivo com uma versão de guia desatualizada, gere:

# Arquivo: whitepapers/fr/00-introduction-serie.qmd
# Alteração:
version: "3.27.6"  ->  version: "{VERSION_ATUAL}"
date: 2026-02-12   ->  date: {hoje}

Patches de correção de categoria (recap cards EN)

Arquivos para atualizar (categoria: "Conceptual" -> "Design"):
- whitepapers/recap-cards/en/c01-trust-calibration.qmd
- whitepapers/recap-cards/en/c02-*.qmd
- whitepapers/recap-cards/en/c03-*.qmd
- whitepapers/recap-cards/en/c04-*.qmd
- whitepapers/recap-cards/en/c05-*.qmd

---

Nota: Este comando foi migrado de um sistema anterior, conforme solicitado pelo usuário.