@damenor/agent-docs 0.1.1 → 0.4.0

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

@@ -1,324 +1,329 @@
 ---
 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.
+  Audits the health of the project documentation. Verifies completeness,
+  currency, consistency, and coverage. Generates a health report with
+  a 0-100 score and action priorities.
+  TRIGGER: When the user says "audit docs", "review documentation",
+  "docs status", "healthy docs", "health check docs", or periodically
+  as part of project maintenance.
 license: Apache-2.0
 metadata:
   author: damenordev
-  version: "1.0"
+  version: '1.0'
 ---
 
 # doc-review
 
-## Cuándo Usar
+## When to Use
 
-- **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
+- **Periodic review**: Monthly or at the end of each sprint
+- **Before releases**: Verify that docs are up to date
+- **CI integration**: As an automatic step in the pipeline
+- **New dev onboarding**: Verify that docs allow getting started
+- **When docs feel outdated**: Sensation that docs don't reflect the code
 
-## Patrones Críticos
+## Critical Patterns
 
-### REGLA #1: Verificar problemas específicos, no solo existencia
+### RULE #1: Check for specific issues, not just existence
 
-No basta con "¿el archivo existe?". Verificar:
+It's not enough to ask "does the file exist?". Check:
 
-| 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 |
+| Issue            | What to look for                                         |
+| ---------------- | -------------------------------------------------------- |
+| Empty docs       | Files with only frontmatter and title                    |
+| Stale docs       | Files without `last-reviewed` in >3 months               |
+| TODO/TBD         | Search for `TODO`, `TBD`, `FIXME`, `PENDING` in content  |
+| Placeholder      | Search for "pending content", "add here", empty sections |
+| Broken wikilinks | `[[link]]` that doesn't resolve to an existing file      |
 
-### REGLA #2: Validar cobertura Diátaxis
+### RULE #2: Validate Diátaxis coverage
 
-Los 4 cuadrantes deben estar cubiertos:
+All 4 quadrants must be covered:
 
 ```
-¿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/
+Is there at least one tutorial?         → tutorials/
+Is there at least one how-to?           → how-to/
+Is there at least one reference file?   → reference/
+Is there at least one explanation?      → explanation/
 ```
 
-Si falta un cuadrante completo, es un gap CRÍTICO.
+If an entire quadrant is missing, it is a CRITICAL gap.
 
-### REGLA #3: Verificar consistencia de CONTEXT.md con el código
+### RULE #3: Verify CONTEXT.md consistency with code
 
 ```
-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
+1. Read CONTEXT.md → list of defined terms
+2. Search code for terms used but not in CONTEXT.md
+3. Search CONTEXT.md for terms that no longer exist in code
+4. Report discrepancies
 ```
 
-### REGLA #4: Validar completitud de ADRs
+### RULE #4: Validate ADR completeness
 
 ```
-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)?
+1. Does every ADR have a valid status? (proposed, accepted, deprecated, superseded)
+2. Is the numbering sequential without gaps?
+3. Do deprecated ADRs have a documented replacement?
+4. Does each ADR meet the 3 criteria (hard to reverse, surprising, trade-off)?
 ```
 
-### REGLA #5: Verificar sincronía de DESIGN.md con el código
+### RULE #5: Verify DESIGN.md sync with code
 
 ```
-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
+1. Read DESIGN.md → extract documented tokens
+2. Read style files (CSS vars, Tailwind config)
+3. Compare documented values vs actual values
+4. Report differences
 ```
 
-### REGLA #6: Verificar que se sigue el protocolo de AGENTS.md
+### RULE #6: Verify AGENTS.md protocol is followed
 
 ```
-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?
+1. Does AGENTS.md exist and have the protocol?
+2. Do agents follow the protocol? (evidence in recent commits)
+3. Does the folder structure match what's documented in 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
+## Review Dimensions
+
+### 1. Completeness
+
+**What to check**:
+
+- Documentation files that should exist but don't
+- Empty sections within existing files
+- Code features without corresponding documentation
+- Undocumented endpoints/functions/components
+
+**Score**:
+| Criterion | Points |
+|-----------|--------|
+| All essential files exist | 0-10 |
+| All sections have real content | 0-10 |
+| All public features are documented | 0-10 |
+
+### 2. Currency
+
+**What to check**:
+
+- Files not updated in >3 months (check if relevant code changed)
+- References to obsolete versions/libraries
+- CHANGELOG.md outdated vs git tags
+- Screenshots or diagrams that don't reflect current UI
+
+**Score**:
+| Criterion | Points |
+|-----------|--------|
+| Docs reflect current state of code | 0-10 |
+| CHANGELOG is up to date | 0-5 |
+| No references to old versions | 0-5 |
+
+### 3. Consistency
+
+**What to check**:
+
+- CONTEXT.md vs code: terms match
+- DESIGN.md vs styles: tokens match
+- ADRs vs implementation: what the ADR says is what's in code
+- docs/README.md map reflects real files
+- Consistent format: frontmatter, naming, language
+
+**Score**:
+| Criterion | Points |
+|-----------|--------|
+| CONTEXT.md matches code | 0-5 |
+| DESIGN.md matches styles | 0-5 |
+| docs/README.md reflects real files | 0-5 |
+| Consistent format across files | 0-5 |
+
+### 4. Coverage
+
+**What to check**:
+
+- Diátaxis: all 4 quadrants are covered
+- Features: each public feature has at least one associated doc
+- API: all endpoints are documented
+- Components: all UI components are in DESIGN.md
+- Errors: common errors have troubleshooting
+
+**Score**:
+| Criterion | Points |
+|-----------|--------|
+| Diátaxis: 4 quadrants covered | 0-10 |
+| API/endpoints documented | 0-5 |
+| UI components in DESIGN.md | 0-5 |
+
+### 5. Quality
+
+**What to check**:
+
+- Real content vs placeholder (no TODO, no "pending")
+- Clear and correct writing
+- Runnable examples in tutorials/how-tos
+- Complete tables in reference
+- No duplication between files
+
+**Score**:
+| Criterion | Points |
+|-----------|--------|
+| No placeholders or TODOs | 0-10 |
+| Runnable examples | 0-5 |
+| No content duplication | 0-5 |
+
+## Health Score
+
+### Calculation
 
 ```
-Puntuación total = Completitud (30) + Actualidad (20) + Consistencia (20) + Cobertura (20) + Calidad (20) = 100
+Total score = Completeness (30) + Currency (20) + Consistency (20) + Coverage (20) + Quality (20) = 100
 ```
 
-### Escala
+### Scale
 
-| 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 |
+| Score  | Status        | Action                              |
+| ------ | ------------- | ----------------------------------- |
+| 90-100 | 🟢 Healthy    | Maintain, periodic review           |
+| 70-89  | 🟡 Acceptable | Prioritized improvements identified |
+| 50-69  | 🟠 Deficient  | Requires significant work           |
+| 0-49   | 🔴 Critical   | Fundamental documentation missing   |
 
-## Formato del Reporte
+## Report Format
 
 ```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 |
+# Documentation Health Report
+
+**Date**: 2024-03-15
+**Project**: [name]
+**Score**: 72/100 🟡
+
+## Summary by Dimension
+
+| Dimension    | Score  | Maximum |
+| ------------ | ------ | ------- |
+| Completeness | 22     | 30      |
+| Currency     | 15     | 20      |
+| Consistency  | 14     | 20      |
+| Coverage     | 12     | 20      |
+| Quality      | 9      | 10      |
+| **Total**    | **72** | **100** |
+
+## Critical Issues 🔴
+
+- [ ] No API documentation exists (reference/api.md)
+- [ ] DESIGN.md has color values that don't match CSS variables
+
+## Important Issues 🟡
+
+- [ ] Missing how-to coverage (empty folder)
+- [ ] 3 ADRs without defined status
+- [ ] CONTEXT.md doesn't include 5 terms used in code
+
+## Suggested Improvements 🟢
+
+- [ ] Add last-reviewed to files without review date
+- [ ] Update CHANGELOG with last 3 releases
+- [ ] Add runnable examples to tutorials/quick-start.md
+
+## Detail by File
+
+| File             | Status         | Issues                |
+| ---------------- | -------------- | --------------------- |
+| README.md        | ✅ OK          | —                     |
+| CHANGELOG.md     | ⚠️ Outdated    | Missing release 2.1.0 |
+| docs/CONTEXT.md  | ⚠️ Incomplete  | 5 terms missing       |
+| docs/DESIGN.md   | 🔴 Out of sync | 3 tokens don't match  |
+| docs/README.md   | ✅ OK          | —                     |
+| reference/api.md | 🔴 Missing     | Does not exist        |
+| tutorials/       | ✅ OK          | —                     |
+| how-to/          | ⚠️ Empty       | No content            |
+| explanation/     | ✅ OK          | —                     |
+| docs/adr/        | ⚠️ Incomplete  | 3 ADRs without status |
 ```
 
-## Proceso de Revisión
+## Review Process
 
-### Paso 1: Inventario
+### Step 1: Inventory
 
 ```
-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
+1. List all existing documentation files
+2. Verify docs/README.md vs real files
+3. Identify missing files based on the stack
 ```
 
-### Paso 2: Verificación por dimensión
+### Step 2: Verification by dimension
 
 ```
-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
+1. Completeness: files, sections, features
+2. Currency: dates, versions, recent changes
+3. Consistency: CONTEXT, DESIGN, ADRs, README
+4. Coverage: Diátaxis, API, components
+5. Quality: placeholders, examples, duplicates
 ```
 
-### Paso 3: Puntuación
+### Step 3: Scoring
 
 ```
-Calcular puntuación por dimensión y total
-Determinar estado general (🟢🟡🟠🔴)
+Calculate score by dimension and total
+Determine overall status (🟢🟡🟠🔴)
 ```
 
-### Paso 4: Generar reporte
+### Step 4: Generate report
 
 ```
-1. Listar problemas críticos primero
-2. Problemas importantes después
-3. Mejoras sugeridas al final
-4. Detalle por archivo
+1. List critical issues first
+2. Important issues next
+3. Suggested improvements at the end
+4. Detail by file
 ```
 
-### Paso 5: Recomendar acciones
+### Step 5: Recommend actions
 
 ```
-Para cada problema crítico:
-- Qué archivo crear/actualizar
-- Qué skill usar (doc-write, doc-design, etc.)
-- Prioridad (inmediata, esta semana, este sprint)
+For each critical issue:
+- Which file to create/update
+- Which skill to use (doc-write, doc-design, etc.)
+- Priority (immediate, this week, this sprint)
 ```
 
-## Comandos
+## Commands
 
-### Verificación rápida
+### Quick verification
 
 ```
-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
+1. List doc files: docs/, tutorials/, how-to/, reference/, explanation/
+2. Search TODOs: rg "TODO|TBD|FIXME|PENDING" --type md
+3. Verify dates: check last-reviewed in frontmatter
+4. Verify wikilinks: search [[...]] and verify they exist
 ```
 
-### Verificación profunda
+### Deep verification
 
 ```
-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
+1. CONTEXT.md vs code: compare defined terms vs used terms
+2. DESIGN.md vs styles: compare documented tokens vs actual ones
+3. ADRs vs implementation: verify that code follows what was decided
+4. Diátaxis: verify coverage of all 4 quadrants
 ```
 
-## Escaladas
+## Escalations
 
-### Cuándo escalar (gap crítico)
+### When to escalate (critical gap)
 
-- 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
+- No quick-start tutorial → onboarding blocked
+- No API reference → integrators blocked
+- Empty CHANGELOG → can't tell what changed between versions
+- No CONTEXT.md → ambiguous terms cause confusion
+- DESIGN.md out of sync → visual inconsistencies
 
-### Acción al escalar
+### Action on escalation
 
-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
+1. Create the issue/task with high priority
+2. Assign to the corresponding skill: `doc-write`, `doc-design`, `doc-scaffold`
+3. Estimate effort
+4. Include in the next sprint
 
-## Recursos
+## Resources
 
-- [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)
+- [Health Checklist](references/health-checklist.md) — Complete audit checklist with scoring rubric
+- Related skills: `doc-write` (write missing docs), `doc-design` (fix DESIGN.md), `doc-scaffold` (create missing structure), `doc-maintain` (sync changes)