@damenor/agent-docs 0.1.0

package/templates/modules/agents/.agents/skills/doc-review/SKILL.md

@@ -0,0 +1,324 @@
+---
+name: doc-review
+description: >
+  Audita la salud de la documentación del proyecto. Verifica completitud,
+  actualización, consistencia y cobertura. Genera un reporte de salud con
+  puntuación 0-100 y prioridades de acción.
+  TRIGGER: Cuando el usuario dice "auditar docs", "revisar documentación",
+  "estado de docs", "docs saludables", "health check docs", o periódicamente
+  como parte del mantenimiento del proyecto.
+license: Apache-2.0
+metadata:
+  author: damenordev
+  version: "1.0"
+---
+
+# doc-review
+
+## Cuándo Usar
+
+- **Revisión periódica**: Mensual o al final de cada sprint
+- **Antes de releases**: Verificar que la doc está actualizada
+- **Integración CI**: Como paso automático en el pipeline
+- **Onboarding de nuevo dev**: Verificar que la doc permite arrancar
+- **Cuando la doc se siente desactualizada**: Sensación de que la doc no refleja el código
+
+## Patrones Críticos
+
+### REGLA #1: Verificar problemas específicos, no solo existencia
+
+No basta con "¿el archivo existe?". Verificar:
+
+| Problema | Qué buscar |
+|----------|------------|
+| Docs vacíos | Archivos con solo frontmatter y título |
+| Docs stale | Archivos sin `last-reviewed` en >3 meses |
+| TODO/TBD | Buscar `TODO`, `TBD`, `FIXME`, `PENDIENTE` en contenido |
+| Placeholder | Buscar "contenido pendiente", "agregar aquí", secciones vacías |
+| Wikilinks rotos | `[[enlace]]` que no resuelve a un archivo existente |
+
+### REGLA #2: Validar cobertura Diátaxis
+
+Los 4 cuadrantes deben estar cubiertos:
+
+```
+¿Hay al menos un tutorial?         → tutorials/
+¿Hay al menos un how-to?           → how-to/
+¿Hay al menos un archivo de referencia? → reference/
+¿Hay al menos una explicación?     → explanation/
+```
+
+Si falta un cuadrante completo, es un gap CRÍTICO.
+
+### REGLA #3: Verificar consistencia de CONTEXT.md con el código
+
+```
+1. Leer CONTEXT.md → lista de términos definidos
+2. Buscar en código términos usados pero no en CONTEXT.md
+3. Buscar en CONTEXT.md términos que ya no existen en código
+4. Reportar discrepancias
+```
+
+### REGLA #4: Validar completitud de ADRs
+
+```
+1. ¿Todo ADR tiene status válido? (proposed, accepted, deprecated, superseded)
+2. ¿La numeración es secuencial sin gaps?
+3. ¿Los ADRs deprecated tienen reemplazo documentado?
+4. ¿Cada ADR cumple los 3 criterios (difícil de revertir, sorprendente, trade-off)?
+```
+
+### REGLA #5: Verificar sincronía de DESIGN.md con el código
+
+```
+1. Leer DESIGN.md → extraer tokens documentados
+2. Leer archivos de estilos (CSS vars, Tailwind config)
+3. Comparar valores documentados vs valores reales
+4. Reportar diferencias
+```
+
+### REGLA #6: Verificar que se sigue el protocolo de AGENTS.md
+
+```
+1. ¿AGENTS.md existe y tiene el protocolo?
+2. ¿Los agentes siguen el protocolo? (evidencia en commits recientes)
+3. ¿La estructura de carpetas coincide con lo documentado en AGENTS.md?
+```
+
+## Dimensiones de Revisión
+
+### 1. Completitud
+
+**Qué verificar**:
+- Archivos de documentación que deberían existir y no existen
+- Secciones vacías dentro de archivos existentes
+- Features del código sin documentación correspondiente
+- Endpoints/funciones/componentes sin documentar
+
+**Puntuación**:
+| Criterio | Puntos |
+|----------|--------|
+| Todos los archivos esenciales existen | 0-10 |
+| Todas las secciones tienen contenido real | 0-10 |
+| Todas las features públicas están documentadas | 0-10 |
+
+### 2. Actualidad
+
+**Qué verificar**:
+- Archivos sin actualización en >3 meses (verificar si el código relevante cambió)
+- Referencias a versiones/librerías obsoletas
+- CHANGELOG.md desactualizado vs tags de git
+- Screenshots o diagramas que no reflejan la UI actual
+
+**Puntuación**:
+| Criterio | Puntos |
+|----------|--------|
+| Docs reflejan el estado actual del código | 0-10 |
+| CHANGELOG está al día | 0-5 |
+| No hay referencias a versiones viejas | 0-5 |
+
+### 3. Consistencia
+
+**Qué verificar**:
+- CONTEXT.md vs código: términos coinciden
+- DESIGN.md vs estilos: tokens coinciden
+- ADRs vs implementación: lo que dice el ADR es lo que está en código
+- docs/README.md mapa refleja archivos reales
+- Formato consistente: frontmatter, nomenclatura, idioma
+
+**Puntuación**:
+| Criterio | Puntos |
+|----------|--------|
+| CONTEXT.md coincide con código | 0-5 |
+| DESIGN.md coincide con estilos | 0-5 |
+| docs/README.md refleja archivos reales | 0-5 |
+| Formato consistente entre archivos | 0-5 |
+
+### 4. Cobertura
+
+**Qué verificar**:
+- Diátaxis: los 4 cuadrantes están cubiertos
+- Features: cada feature pública tiene al menos un doc asociado
+- API: todos los endpoints están documentados
+- Componentes: todos los componentes UI están en DESIGN.md
+- Errores: errores comunes tienen troubleshooting
+
+**Puntuación**:
+| Criterio | Puntos |
+|----------|--------|
+| Diátaxis: 4 cuadrantes cubiertos | 0-10 |
+| API/endpoints documentados | 0-5 |
+| Componentes UI en DESIGN.md | 0-5 |
+
+### 5. Calidad
+
+**Qué verificar**:
+- Contenido real vs placeholder (no TODO, no "pendiente")
+- Escritura clara y correcta
+- Ejemplos ejecutables en tutoriales/how-tos
+- Tablas completas en referencia
+- Sin duplicación entre archivos
+
+**Puntuación**:
+| Criterio | Puntos |
+|----------|--------|
+| Sin placeholders ni TODOs | 0-10 |
+| Ejemplos ejecutables | 0-5 |
+| Sin duplicación de contenido | 0-5 |
+
+## Puntuación de Salud
+
+### Cálculo
+
+```
+Puntuación total = Completitud (30) + Actualidad (20) + Consistencia (20) + Cobertura (20) + Calidad (20) = 100
+```
+
+### Escala
+
+| Puntuación | Estado | Acción |
+|------------|--------|--------|
+| 90-100 | 🟢 Saludable | Mantener, revisión periódica |
+| 70-89 | 🟡 Aceptable | Mejoras prioritarias identificadas |
+| 50-69 | 🟠 Deficiente | Requiere trabajo significativo |
+| 0-49 | 🔴 Crítico | Documentación fundamental faltante |
+
+## Formato del Reporte
+
+```markdown
+# Reporte de Salud de Documentación
+
+**Fecha**: 2024-03-15
+**Proyecto**: [nombre]
+**Puntuación**: 72/100 🟡
+
+## Resumen por Dimensión
+
+| Dimensión | Puntuación | Máximo |
+|-----------|------------|--------|
+| Completitud | 22 | 30 |
+| Actualidad | 15 | 20 |
+| Consistencia | 14 | 20 |
+| Cobertura | 12 | 20 |
+| Calidad | 9 | 10 |
+| **Total** | **72** | **100** |
+
+## Problemas Críticos 🔴
+
+- [ ] No existe documentation de API (reference/api.md)
+- [ ] DESIGN.md tiene valores de colores que no coinciden con CSS variables
+
+## Problemas Importantes 🟡
+
+- [ ] Falta cobertura de how-tos (carpeta vacía)
+- [ ] 3 ADRs sin status definido
+- [ ] CONTEXT.md no incluye 5 términos usados en código
+
+## Mejoras Sugeridas 🟢
+
+- [ ] Agregar last-reviewed a archivos sin fecha de revisión
+- [ ] Actualizar CHANGELOG con últimos 3 releases
+- [ ] Agregar ejemplos ejecutables a tutorials/quick-start.md
+
+## Detalle por Archivo
+
+| Archivo | Estado | Issues |
+|---------|--------|--------|
+| README.md | ✅ OK | — |
+| CHANGELOG.md | ⚠️ Desactualizado | Falta release 2.1.0 |
+| docs/CONTEXT.md | ⚠️ Incompleto | 5 términos faltantes |
+| docs/DESIGN.md | 🔴 Desincronizado | 3 tokens no coinciden |
+| docs/README.md | ✅ OK | — |
+| reference/api.md | 🔴 Faltante | No existe |
+| tutorials/ | ✅ OK | — |
+| how-to/ | ⚠️ Vacío | Sin contenido |
+| explanation/ | ✅ OK | — |
+| docs/adr/ | ⚠️ Incompleto | 3 ADRs sin status |
+```
+
+## Proceso de Revisión
+
+### Paso 1: Inventario
+
+```
+1. Listar todos los archivos de documentación existentes
+2. Verificar docs/README.md vs archivos reales
+3. Identificar archivos faltantes según el stack
+```
+
+### Paso 2: Verificación por dimensión
+
+```
+1. Completitud: archivos, secciones, features
+2. Actualidad: fechas, versiones, cambios recientes
+3. Consistencia: CONTEXT, DESIGN, ADRs, README
+4. Cobertura: Diátaxis, API, componentes
+5. Calidad: placeholders, ejemplos, duplicados
+```
+
+### Paso 3: Puntuación
+
+```
+Calcular puntuación por dimensión y total
+Determinar estado general (🟢🟡🟠🔴)
+```
+
+### Paso 4: Generar reporte
+
+```
+1. Listar problemas críticos primero
+2. Problemas importantes después
+3. Mejoras sugeridas al final
+4. Detalle por archivo
+```
+
+### Paso 5: Recomendar acciones
+
+```
+Para cada problema crítico:
+- Qué archivo crear/actualizar
+- Qué skill usar (doc-write, doc-design, etc.)
+- Prioridad (inmediata, esta semana, este sprint)
+```
+
+## Comandos
+
+### Verificación rápida
+
+```
+1. Listar archivos de doc: docs/, tutorials/, how-to/, reference/, explanation/
+2. Buscar TODOs: rg "TODO|TBD|FIXME|PENDIENTE" --type md
+3. Verificar fechas: revisar last-reviewed en frontmatter
+4. Verificar wikilinks: buscar [[...]] y verificar que existen
+```
+
+### Verificación profunda
+
+```
+1. CONTEXT.md vs código: comparar términos definidos vs usados
+2. DESIGN.md vs estilos: comparar tokens documentados vs reales
+3. ADRs vs implementación: verificar que el código sigue lo decidido
+4. Diátaxis: verificar cobertura de los 4 cuadrantes
+```
+
+## Escaladas
+
+### Cuándo escalar (gap crítico)
+
+- Sin tutorial de quick-start → onboarding bloqueado
+- Sin referencia de API → integradores bloqueados
+- CHANGELOG vacío → no se sabe qué cambió entre versiones
+- Sin CONTEXT.md → términos ambiguos causan confusión
+- DESIGN.md desincronizado → inconsistencias visuales
+
+### Acción al escalar
+
+1. Crear el issue/tarea con prioridad alta
+2. Asignar al skill correspondiente: `doc-write`, `doc-design`, `doc-scaffold`
+3. Estimar esfuerzo
+4. Incluir en el siguiente sprint
+
+## Recursos
+
+- [Health Checklist](references/health-checklist.md) — Checklist completo de auditoría con rúbrica de puntuación
+- Skills relacionados: `doc-write` (escribir docs faltantes), `doc-design` (arreglar DESIGN.md), `doc-scaffold` (crear estructura faltante), `doc-maintain` (sincronizar cambios)

package/templates/modules/agents/.agents/skills/doc-review/references/health-checklist.md

@@ -0,0 +1,290 @@
+---
+created: "2024-01-15"
+status: active
+type: reference
+tags: [auditoria, checklist, salud, documentacion]
+---
+
+# Checklist de Salud de Documentación
+
+## Checklist por Tipo de Archivo
+
+### README.md
+
+- [ ] Tiene descripción clara del proyecto
+- [ ] Instrucciones de instalación actualizadas
+- [ ] Link a docs/ para documentación detallada
+- [ ] Stack tecnológico mencionado
+- [ ] Badges o indicadores de estado (CI, cobertura)
+- [ ] Sin referencias a features eliminadas
+
+### CHANGELOG.md
+
+- [ ] Sigue formato Keep a Changelog o similar
+- [ ] Última versión refleja el release más reciente
+- [ ] Fechas en cada entrada
+- [ ] Tipos de cambio separados (Added, Changed, Fixed, etc.)
+- [ ] Sin gaps entre versiones
+
+### AGENTS.md
+
+- [ ] Protocolo "antes de cada tarea" documentado
+- [ ] Protocolo "después de cada tarea" documentado
+- [ ] Protocolo de subdelegación incluido
+- [ ] Comandos esenciales actualizados
+- [ ] Stack tecnológico correcto
+- [ ] Skills disponibles listados con descripción
+
+### docs/README.md
+
+- [ ] Mapa completo de archivos de documentación
+- [ ] Reglas de crecimiento (cuándo agregar docs)
+- [ ] Convenciones de nomenclatura
+- [ ] Todos los archivos listados realmente existen
+- [ ] No hay archivos existentes sin listar
+
+### docs/CONTEXT.md
+
+- [ ] Todos los términos tienen definición
+- [ ] No hay términos del código que falten
+- [ ] Relaciones entre términos documentadas
+- [ ] Términos ambiguos marcados con ⚠️
+- [ ] Formato consistente (tabla o lista)
+
+### docs/adr/
+
+- [ ] TEMPLATE.md existe y está actualizado
+- [ ] Numeración secuencial sin gaps
+- [ ] Cada ADR tiene status (proposed/accepted/deprecated)
+- [ ] Cada ADR cumple los 3 criterios
+- [ ] ADRs deprecated tienen reemplazo indicado
+- [ ] No hay decisiones importantes sin ADR
+
+### docs/DESIGN.md
+
+- [ ] Frontmatter YAML con secciones completas (colors, typography, spacing, rounded, elevation, components)
+- [ ] Tokens referenciados con notación `{seccion.token}`
+- [ ] Valores coinciden con CSS vars / Tailwind config
+- [ ] Sección overview en markdown
+- [ ] Componentes documentados con variantes
+- [ ] Breakpoints documentados
+
+### tutorials/
+
+- [ ] Al menos un tutorial de quick-start
+- [ ] Prerequisitos claros y verificables
+- [ ] Verificación ✅ al final de cada paso
+- [ ] Código completo y ejecutable
+- [ ] Un concepto por tutorial
+- [ ] Resumen al final
+
+### how-to/
+
+- [ ] Cada guía resuelve UN problema específico
+- [ ] Pasos directos sin explicación de conceptos
+- [ ] Resultado esperado documentado
+- [ ] Asume conocimiento del lector
+- [ ] Máximo 10 pasos por guía
+
+### reference/
+
+- [ ] Tablas para parámetros/props/campos
+- [ ] Todos los valores, tipos y defaults documentados
+- [ ] Ejemplos mínimos por caso de uso
+- [ ] Códigos de error incluidos
+- [ ] Sin narrativa ni explicaciones (eso va en explanation/)
+
+### explanation/
+
+- [ ] Contexto histórico incluido
+- [ ] Alternativas consideradas mencionadas
+- [ ] Vinculación con ADRs cuando aplica
+- [ ] Enfoque en "por qué" no en "cómo"
+- [ ] Sin instrucciones paso a paso (eso va en how-to/)
+
+---
+
+## Rúbrica de Puntuación
+
+### Completitud (máximo: 30 puntos)
+
+| Criterio | 10 | 5 | 0 |
+|----------|-----|-----|-----|
+| Archivos esenciales | Todos existen | Faltan 1-2 | Faltan 3+ |
+| Secciones con contenido | Todas tienen contenido real | 1-2 secciones vacías | 3+ secciones vacías |
+| Features documentadas | Todas las features públicas | >75% documentadas | <75% documentadas |
+
+### Actualidad (máximo: 20 puntos)
+
+| Criterio | Puntos | Cómo verificar |
+|----------|--------|----------------|
+| Docs reflejan código actual | 0-10 | Comparar con `git log --since="3 months ago"` |
+| CHANGELOG al día | 0-5 | Comparar con git tags |
+| Sin referencias obsoletas | 0-5 | Buscar versiones viejas de librerías |
+
+### Consistencia (máximo: 20 puntos)
+
+| Criterio | Puntos | Cómo verificar |
+|----------|--------|----------------|
+| CONTEXT.md coincide con código | 0-5 | Comparar términos definidos vs usados |
+| DESIGN.md coincide con estilos | 0-5 | Comparar tokens vs CSS vars/Tailwind |
+| docs/README.md refleja archivos | 0-5 | Comparar mapa vs filesystem |
+| Formato consistente | 0-5 | Verificar frontmatter, idioma, nomenclatura |
+
+### Cobertura (máximo: 20 puntos)
+
+| Criterio | Puntos | Cómo verificar |
+|----------|--------|----------------|
+| Diátaxis 4 cuadrantes | 0-10 | Al menos un archivo en cada carpeta |
+| API/endpoints documentados | 0-5 | Comparar rutas de código con reference/ |
+| Componentes UI en DESIGN.md | 0-5 | Comparar componentes de código con DESIGN.md |
+
+### Calidad (máximo: 10 puntos)
+
+| Criterio | Puntos | Cómo verificar |
+|----------|--------|----------------|
+| Sin placeholders/TODOs | 0-5 | `rg "TODO|TBD|PENDIENTE|agregar" --type md` |
+| Ejemplos ejecutables | 0-3 | Verificar código en tutoriales/how-tos |
+| Sin duplicación | 0-2 | Buscar contenido idéntico entre archivos |
+
+---
+
+## Problemas Comunes y Soluciones
+
+### Problema: Archivo con solo título y frontmatter
+
+**Causa**: Se creó como placeholder y nunca se completó
+
+**Solución**: Usar `doc-write` para escribir contenido real o eliminar el archivo
+
+### Problema: CONTEXT.md desactualizado
+
+**Causa**: Se agregaron términos al código sin actualizar CONTEXT
+
+**Solución**: Usar `doc-write` para agregar términos faltantes. Buscar en código: nombres de módulos, clases, interfaces, tipos principales
+
+### Problema: DESIGN.md no coincide con CSS
+
+**Causa**: Se cambiaron estilos sin actualizar DESIGN.md
+
+**Solución**: Usar `doc-design` para re-extraer tokens del código y actualizar
+
+### Problema: ADRs sin status
+
+**Causa**: Se crearon como proposed y nunca se actualizó el status
+
+**Solución**: Revisar cada ADR y actualizar status según la realidad actual
+
+### Problema: Wikilinks rotos
+
+**Causa**: Se renombró o eliminó un archivo sin actualizar las referencias
+
+**Solución**: Buscar todos los `[[enlace]]` y verificar que el archivo existe
+
+### Problema: How-to que explica conceptos
+
+**Causa**: Confusión entre how-to y explanation
+
+**Solución**: Extraer las explicaciones a explanation/ y dejar solo los pasos en how-to
+
+### Problema: Tutorial sin verificación por paso
+
+**Causa**: Se escribió sin seguir el patrón de tutorial
+
+**Solución**: Agregar sección "✅ Verificación" al final de cada paso
+
+### Problema: Referencia con prosa narrativa
+
+**Causa**: Se escribió referencia como si fuera tutorial
+
+**Solución**: Convertir prosa a tablas y listas. Mover narrativa a explanation/
+
+---
+
+## Plantilla de Reporte de Salud
+
+```markdown
+# 🏥 Reporte de Salud — Documentación
+
+**Fecha**: [YYYY-MM-DD]
+**Revisor**: [agente/humano]
+**Proyecto**: [nombre]
+
+---
+
+## 📊 Puntuación General: [XX]/100 [🟢🟡🟠🔴]
+
+| Dimensión | Puntos | Máximo | Estado |
+|-----------|--------|--------|--------|
+| Completitud | XX | 30 | 🟢🟡🟠🔴 |
+| Actualidad | XX | 20 | 🟢🟡🟠🔴 |
+| Consistencia | XX | 20 | 🟢🟡🟠🔴 |
+| Cobertura | XX | 20 | 🟢🟡🟠🔴 |
+| Calidad | XX | 10 | 🟢🟡🟠🔴 |
+
+---
+
+## 🔴 Crítico (resolver inmediatamente)
+
+1. **[problema]** → [archivo afectado] → [acción sugerida]
+
+## 🟡 Importante (resolver este sprint)
+
+1. **[problema]** → [archivo afectado] → [acción sugerida]
+
+## 🟢 Mejora (resolver cuando sea posible)
+
+1. **[problema]** → [archivo afectado] → [acción sugerida]
+
+---
+
+## 📁 Detalle por Archivo
+
+| Archivo | Estado | Puntuación | Issues |
+|---------|--------|------------|--------|
+| README.md | ✅ | 10/10 | — |
+| docs/CONTEXT.md | ⚠️ | 6/10 | 3 términos faltantes |
+| ... | ... | ... | ... |
+
+---
+
+## 📋 Acciones Recomendadas
+
+### Prioridad Inmediata
+- [ ] [acción 1] → usar skill `[skill-name]`
+- [ ] [acción 2] → usar skill `[skill-name]`
+
+### Esta Semana
+- [ ] [acción 3] → usar skill `[skill-name]`
+
+### Este Sprint
+- [ ] [acción 4] → usar skill `[skill-name]`
+
+---
+
+*Próxima revisión sugerida: [YYYY-MM-DD]*
+```
+
+---
+
+## Cuándo Escalar
+
+### Gaps críticos que bloquean
+
+| Gap | Impacto | Acción |
+|-----|---------|--------|
+| Sin tutorial de quick-start | Onboarding bloqueado | Crear con `doc-write` inmediatamente |
+| Sin referencia de API | Integradores bloqueados | Crear con `doc-write` |
+| CHANGELOG vacío | No hay historial de cambios | Crear entradas para cada versión |
+| Sin CONTEXT.md | Términos ambiguos | Crear con `doc-write` |
+| Sin AGENTS.md | Agentes sin protocolo | Crear con `doc-scaffold` |
+| DESIGN.md desincronizado >5 tokens | Inconsistencias visuales | Arreglar con `doc-design` |
+
+### Gaps importantes que degradan
+
+| Gap | Impacto | Acción |
+|-----|---------|--------|
+| Cuadrante Diátaxis vacío | Cobertura incompleta | Crear contenido con `doc-write` |
+| ADRs sin status | Confusión sobre decisiones | Actualizar status |
+| 3+ TODOs en docs | Contenido incompleto | Completar o eliminar |
+| docs/README.md desactualizado | Mapa incorrecto | Actualizar |