FlorianBruniaux/claude-code-ultimate-guide

source-command-audit-whitepapers

Usa esta habilidad cuando el usuario solicite ejecutar el comando migrado audit-whitepapers.

Plantilla de Comando

Auditoría de Whitepapers y Recap Cards

Auditoría integral de frescura y calidad para todos los whitepapers (FR + EN) y recap cards (FR + EN). Puntúa cada documento en relación con la versión actual de la guía, verifica la paridad FR/EN y valida la consistencia de los metadatos.

Argumentos

• --fix - Genera sugerencias de actualización y parches de frontmatter (no modifica archivos)
• --verbose - Muestra todos los criterios, incluidos los que pasan, no solo los fallos
• --cards-only - Audita solo los recap cards (omite los whitepapers principales)
• --wp-only - Audita solo los whitepapers principales (omite los recap cards)

Uso

/audit-whitepapers                  # Auditoría completa, solo fallos
/audit-whitepapers --fix            # Auditoría + sugerencias de actualización priorizadas
/audit-whitepapers --verbose        # Detalles completos para todos los criterios
/audit-whitepapers --cards-only     # Solo recap cards
/audit-whitepapers --wp-only        # Solo whitepapers

---

Fase 1: Descubrimiento

Objetivo: Localizar e inventariar todos los documentos auditables.

Pasos

1. Leer la versión actual de la guía: Lee el archivo VERSION en la raíz del proyecto. Esta es la versión objetivo con la que todos los documentos deben estar sincronizados.

2. Escanear directorios en busca de archivos .qmd:

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

3. Clasificar cada archivo:

   • Whitepaper principal: archivos que coinciden con [0-9][0-9]-*.qmd en whitepapers/fr/ o whitepapers/en/
   • Cheatsheet: archivos que coinciden con *cheatsheet*.qmd (se rastrean por separado, no se puntúan)
   • Whitepaper personalizado: archivos que coinciden con *-whitepaper.qmd o *-cheatsheet.qmd de socios externos (strangebee, purchasely, devwithai) -- excluidos de la puntuación, listados por separado
   • Recap card: todos los archivos .qmd en recap-cards/fr/ o recap-cards/en/
   • Bundle/include: fiches-recap-serie.qmd, archivos en el subdirectorio fiches/ -- excluidos (son documentos compuestos)

4. Analizar el frontmatter YAML de cada archivo incluido (leer entre el primer --- y el segundo ---). Extrae:

   • title, subtitle, author, date
   • version (versión de la guía rastreada en los WPs principales y recap cards)
   • wp-version (semver propio del whitepaper, solo en WPs principales)
   • guide-version (campo de versión explícita de la guía utilizado en los recap cards)
   • card-number, category, difficulty (solo recap cards)
   • series (solo WPs principales)

5. Mostrar resumen del descubrimiento:

   Versión de la guía: {VERSION}
   Encontrados: {N} whitepapers principales ({FR}/{EN} FR/EN), {N} recap cards ({FR}/{EN} FR/EN)
   Excluidos: {N} archivos personalizados (strangebee, purchasely, devwithai), {N} archivos bundle
   

---

Fase 2: Análisis de Brecha de Versiones (40 puntos por archivo)

Objetivo: Puntuar qué tan actualizado está cada documento en relación con la guía.

Lógica de comparación Semver

Analiza las cadenas de versión como MAYOR.MENOR.PARCHE. La métrica de desactualización es brecha_menor = version_actual_menor - version_archivo_menor (usando la misma MAYOR). Si MAYOR difiere, se trata como crítico.

Para los whitepapers principales, el campo de versión de la guía es version. Para los recap cards, el campo de versión de la guía es guide-version (se recurre a version si está ausente).

Tabla de puntuación

Criterio	Puntos	Detección
Versión de guía actual (0-1 menores detrás)	15	brecha_menor <= 1
Versión de guía reciente (2-3 menores detrás)	10	brecha_menor 2-3 (crédito parcial, reemplaza los 15)
Versión de guía antigua (4-10 menores detrás)	5	brecha_menor 4-10 (crédito parcial)
Campo wp-version presente y semver válido	5	El campo existe Y coincide con \d+\.\d+\.\d+ (solo WP)
wp-version consistente con el par FR/EN	10	Mismo valor de wp-version en el archivo contraparte (solo WP)
guide-version consistente con el par FR/EN	10	Mismo guide-version (o version) en la contraparte (cards)

Etiquetas de frescura:

• 0-1 menor detrás: Fresco
• 2-3 menores detrás: Desactualizado
• 4-10 menores detrás: Muy desactualizado
• 11+ menores detrás: Crítico

Nota: Los 15, 10, 5 puntos para la versión de la guía son mutuamente excluyentes (se otorga solo el nivel más alto aplicable).

---

Fase 3: Comprobación de Desactualización de Contenido (20 puntos por archivo)

Objetivo: Detectar si las secciones de la guía que cubre un whitepaper han cambiado desde su última actualización.

Mapeo whitepaper-guía (incorporado)

WP#	Prefijo nombre FR	Prefijo nombre EN	Secciones de la guía
00	00-introduction	00-series-introduction	guide/ultimate-guide.md Cap.1-2
01	01-prompts	01-effective-prompts	Cap.2 secciones de prompting
02	02-personnalisation	02-customization	Cap.3 Memoria, Cap.4 Agentes, Cap.5 Habilidades
03	03-securite	03-security	Cap.7 Hooks, secciones de seguridad
04	04-architecture	04-architecture	Cap.2 internos, secciones de arquitectura
05	05-equipe	05-team	Cap.3 config de equipo, Cap.9 CI/CD
06	06-privacy	06-privacy	Cap.2 secciones de datos/privacidad
07	07-guide-reference	07-reference-guide	Cap.10 Referencia
08	08-agent-teams	08-agent-teams	Cap.9 equipos de agentes
09	09-apprendre	09-learning	guide/roles/learning-with-ai.md
10	10-budget	10-ai-budget	Contenido de negocio/ROI

Pasos

1. Para cada whitepaper principal, extrae el campo date. Si la fecha no tiene formato YYYY-MM-DD, analízala (ej., "2026-02-12" o "Marzo 2026").
2. Ejecuta git log --since="{date}" --oneline -- guide/ultimate-guide.md guide/roles/ guide/core/ para contar los commits que afectaron al contenido de la guía desde la fecha del whitepaper.
3. Puntúa:

Criterio	Puntos	Detección
Sin commits de guía desde la fecha del wp	10	git log devuelve 0 commits
Pocos commits desde la fecha del wp (1-5)	7	1-5 commits (parcial)
Commits moderados (6-15)	4	6-15 commits (parcial)
Muchos commits (>15)	0	Más de 15 commits
Mapeo definido para este WP	5	El número de WP está en la tabla de mapeo anterior
Historial de Git accesible	5	El comando git log se ejecuta sin error

Recap cards: Omite el análisis detallado de git. Otorga una puntuación fija de desactualización basada en brecha_menor:

• 0-1 detrás: 20 pts
• 2-3 detrás: 15 pts
• 4-10 detrás: 8 pts
• 11+ detrás: 0 pts

---

Fase 4: Comprobación de Paridad FR/EN (20 puntos por archivo)

Objetivo: Cada documento debe tener una contraparte completa y consistente en versión en el otro idioma.

Estrategia de emparejamiento

Whitepapers principales: Empareja por el prefijo numérico de dos dígitos (ej., 00, 03, 10). Los nombres de archivo FR y EN difieren, pero el prefijo es consistente.

Recap cards: Empareja por el nombre de archivo idéntico (ambos directorios de idioma usan los mismos nombres de archivo).

Tabla de puntuación

Criterio	Puntos	Detección
Existe archivo contraparte en el otro idioma	10	Archivo con prefijo coincidente (WP) o nombre idéntico (cards) encontrado
wp-version coincide entre pares	5	Mismo valor de wp-version (solo WP)
La versión de la guía coincide entre pares	5	Mismo valor de version/guide-version

Puntúa tanto los archivos FR como EN de un par de manera idéntica en paridad (si el par está completo, ambos obtienen 20; si falta uno, el archivo existente puntúa 0 en paridad).

---

Fase 5: Calidad de Metadatos (20 puntos por archivo)

Objetivo: Validar la integridad del frontmatter, los formatos de los campos y la consistencia entre archivos del mismo tipo.

Whitepapers principales (20 puntos máximo)

Criterio	Puntos	Detección
Campos obligatorios presentes	6	Tiene todos: title, subtitle, author, date, version, wp-version, series
version sigue el patrón semver	3	Coincide con \d+\.\d+\.\d+
wp-version sigue el patrón semver	3	Coincide con \d+\.\d+\.\d+
date es analizable y no está en el futuro	3	Fecha válida, no posterior a hoy
El valor de series es consistente	2	Igual a "Codex Ultimate Guide"
No falta wp-version (no se deja vacío o ausente)	3	El campo tiene un valor no vacío

Recap cards (20 puntos máximo)

Criterio	Puntos	Detección
Campos obligatorios presentes	5	Tiene todos: title, subtitle, card-number, category, difficulty, guide-version, author, version, date
card-number coincide con el prefijo del nombre de archivo	4	Ej., C01 en card-number coincide con c01- en el nombre de archivo
category válido para el idioma	4	FR: uno de "Technique", "Methodologie", "Conception"; EN: uno de "Technical", "Methodology", "Design" (marcar "Conceptual" como inconsistente en EN)
difficulty es un valor válido	3	Uno de: "beginner", "intermediate", "advanced"
Los campos guide-version y version coinciden entre sí	4	Ambos campos existen y tienen el mismo valor dentro del mismo archivo

Problema conocido a detectar automáticamente: Las tarjetas de la serie C en EN usan dos valores de categoría diferentes ("Conceptual" en c01-c05, "Design" en c06+). Marca esta inconsistencia explícitamente en la sección de Problemas de Metadatos del informe.

---

Fase 6: Puntuación y Calificación

Fórmula de puntuación (por archivo)

Total = Brecha de Versión (40) + Desactualización de Contenido (20) + Paridad FR/EN (20) + Calidad de Metadatos (20)
Puntuación = (Total / 100) * 100  [como porcentaje]

Escala de calificación

Calificación	Puntuación	Estado
A	90-100	Fresco, totalmente sincronizado
B	80-89	Bueno (umbral de producción)
C	70-79	Necesita actualización pronto
D	60-69	Desactualizado, se debe priorizar
F	<60	Crítico: contenido probablemente obsoleto

Puntuación de salud general

Salud Ponderada = (Suma de puntuaciones de WP * 2 + Suma de puntuaciones de cards * 1) / (Recuento de WP * 2 + Recuento de cards * 1)

Los whitepapers se ponderan 2x porque tienen de 20 a 80 páginas cada uno, frente a los recap cards de 2 páginas. Un whitepaper desactualizado conlleva más riesgo.

---

Fase 7: Informe

Genera el siguiente informe en Markdown. Usa bloques <details> para los desgloses de archivos individuales y mantener el nivel superior escaneable.

# Auditoría de Whitepapers y Recap Cards

**Fecha**: {hoy}
**Versión de la Guía**: {VERSION}
**Salud General**: {puntuación}% ({calificación})
**Archivos Auditados**: {total} ({wp_count} whitepapers, {card_count} recap cards)

---

## Panel de Estado de Versiones

| Estado | Whitepapers | Recap Cards | Total |
|--------|-------------|-------------|-------|
| Fresco (0-1 menor detrás)   | N | N | N |
| Desactualizado (2-3 menores detrás)   | N | N | N |
| Muy desactualizado (4-10 detrás)   | N | N | N |
| Crítico (11+ detrás)      | N | N | N |

**Versiones actualmente en uso**:
- WP principal 00-09: {version} ({gap} versiones menores detrás)
- WP principal 10: {version} ({gap} versiones menores detrás)
- Recap cards: {guide-version} ({gap} versiones menores detrás)

---

## Puntuaciones de Whitepapers

| WP# | Título | version | Gap | wp-version | Paridad | Puntuación | Calificación |
|-----|-------|---------|-----|------------|--------|-------|-------|
| 00  | ...   | ...     | -N  | ...        | OK/gap | N%    | X     |
...

<details>
<summary>Desglose de criterios individuales (WP 00)</summary>

| Fase | Criterio | Resultado | Puntos |
|-------|-----------|--------|--------|
| Brecha de Versión | Versión de guía actual | Crítico (-11) | 0/15 |
| Brecha de Versión | wp-version semver válido | OK | 5/5 |
| ... | ... | ... | ... |
| **Total** | | | **N/100** |
</details>

---

## Puntuaciones de Recap Cards

| Serie | Cards | guide-version promedio | Gap promedio | Puntuación promedio | Calificación |
|--------|-------|-------------------|---------|-----------|-------|
| T (Técnica)    | 22 | ... | -N | N% | X |
| M (Metodología)  | 22 | ... | -N | N% | X |
| C (Conceptual)   | 13 | ... | -N | N% | X |

<details>
<summary>Puntuaciones individuales de cards</summary>

| Card | Categoría | guide-version | Gap | Paridad | Metadatos | Puntuación | Calificación |
|------|----------|---------------|-----|--------|----------|-------|-------|
...
</details>

---

## Informe de Paridad FR/EN

### Whitepapers
| WP# | FR | EN | Coincidencia de wp-version | Coincidencia de version |
|-----|----|----|------------------|---------------|
...

### Recap Cards
- **Recuento FR**: {N} | **Recuento EN**: {N}
- **FR faltantes**: [lista o "Ninguno"]
- **EN faltantes**: [lista o "Ninguno"]
- **Desajustes de versión**: [lista o "Ninguno"]

---

## Problemas de Metadatos

### Conocido: Inconsistencia de Categoría en Recap Cards EN
Las tarjetas de la serie C en EN usan dos valores diferentes para la categoría "Conceptual/Design":
- "Conceptual": c01, c02, c03, c04, c05
- "Design": c06, c07, c08, ...
Recomendación: estandarizar a "Design" para que coincida con la terminología de la guía.
Archivos afectados: whitepapers/recap-cards/en/c01-*.qmd hasta c05-*.qmd (cambiar "Conceptual" a "Design")

### Otros problemas
[Enumera cualquier campo faltante, formato incorrecto, problemas de fecha...]

---

## Acciones Prioritarias

### Crítico (Calificación F, 11+ versiones detrás)
[Enumera whitepapers específicos con rutas de archivo]

### Alto (Calificación D-F, 2+ versiones detrás)
[Enumera archivos específicos]

### Medio (Calidad de metadatos, correcciones de categoría)
[Enumera problemas específicos]

### Bajo (Pulido, alineación de fechas)
[Enumera problemas específicos]

---

## Próximos Pasos

1. Ejecuta `/update-whitepapers --since {version_mas_antigua}` para actualizar todos los WPs desactualizados
2. Corrige la inconsistencia de categoría en EN (5 archivos: c01 a c05, cambiar "Conceptual" a "Design")
3. Vuelve a ejecutar `/audit-whitepapers` después de las actualizaciones para hacer seguimiento del progreso
4. Objetivo: 80%+ de salud (Calificación B) en todos los archivos

---

Modo de Corrección (--fix)

Cuando se pasa --fix, añade una sección de Sugerencias de Corrección después del informe. Esta sección proporciona parches concretos pero NO modifica ningún archivo.

Parches de versión de frontmatter

Para cada archivo con una versión de guía desactualizada, genera:

# Archivo: whitepapers/fr/00-introduction-serie.qmd
# Cambio:
version: "3.27.6"  ->  version: "{VERSION_ACTUAL}"
date: 2026-02-12   ->  date: {hoy}

Parches de corrección de categoría (recap cards EN)

Archivos a actualizar (categoría: "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