---
paths:
  - "**/scripts/verificar-*.js"
  - "**/MANUAL_USO.md"
  - "**/manifiestos/**"
  - "**/INVENTARIO.md"
---
# Regla: Auditorías documentales estructurales en SWL

Esta regla es **OBLIGATORIA** y aplica a todo agente o agente humano que
ejecute, reporte o consuma resultados de:

- `node scripts/verificar-docs-vs-codigo.js` (verificador docs↔código)
- `node scripts/verificar-release.js` (gate pre-publish)
- `npm run test:manifest` (coherencia modulos/hooks)
- `/swl:claudemd audit` (auditoría de CLAUDE.md)
- Cualquier comando o script que reporte un veredicto agregado tipo
  "N/N checks OK" como prueba de calidad documental.

Es la **versión específica al sistema SWL** de la regla global
`~/.claude/rules/arreglar-al-detectar.md § Aplicación a auditorías`.

---

## Principio

> Una auditoría documental no se declara "limpia" hasta que se ha medido
> **profundidad**, no solo **presencia**. El verificador automático puede
> dar verde con docs vacías o infra-documentadas si su métrica es laxa.
> El agente que reporta resultados al usuario es responsable de distinguir
> entre **gate formal pasado** y **dominio realmente sano**.

---

## Por qué existe esta regla

Sesión 2026-05-16, post-release v1.6.0: el agente ejecutó dos auditorías
documentales consecutivas (Opción C release v1.6.0 + auditoría tras
`/swl:exportar-vault`) y reportó "verde" en ambas. El usuario detectó que:

- `agent-browser` estaba en el sistema desde ADR-0018 (skill + manifest +
  integración con `investigador-swl` y `web-fetcher-routing`) pero **ausente
  en `MANUAL_USO.md`**.
- `ADR-0022` (TUI custom zero-deps, propio del release v1.6.0) **no estaba
  referenciado** en `MANUAL_USO.md`.
- 22 de 58 variables `SWL_*` que existen en `hooks/` y `scripts/` **no
  estaban documentadas** ni en `docs/variables-entorno.md` ni en
  `MANUAL_USO.md`.
- El verificador `scripts/verificar-docs-vs-codigo.js` reportaba "9 checks
  OK" porque sus checks de comandos contaban menciones (presencia), no
  profundidad. WARN consolidado de comandos infra-documentados se reportaba
  como "OK".

Las dos auditorías fueron **cosméticas**, no estructurales. El gate verde
ocultaba 22 variables huérfanas y 19 ADRs no referenciados.

---

## Gates de profundidad obligatorios

### Para comandos `/swl:*`

Un comando se considera **infra-documentado** si en `MANUAL_USO.md`:

- Tiene **menos de 4 menciones** Y
- Es un comando "no trivial" (excluir `ayuda`, `salud`, `modelo`,
  `contexto`, `dashboard` que son operacionales simples).

Un comando infra-documentado debe tener al menos:

1. Una sección dedicada con encabezado `### \`/swl:<nombre>\``.
2. Subsección "**Uso**" con el patrón completo de flags.
3. Subsección "**¿Qué hace?**" con descripción funcional.
4. Subsección "**Cuándo usarlo**" con casos de uso.
5. Al menos un **ejemplo concreto** de invocación con output esperado.
6. Subsección "**Gotchas**" o "**Troubleshooting**" si el comando tiene
   dependencias externas (MCP, herramientas opt-in, paths críticos).

### Para variables de entorno `SWL_*`

Cobertura **completa, no muestral**:

- Toda variable `SWL_*` que aparezca en `hooks/` o `scripts/` DEBE estar
  documentada en `docs/variables-entorno.md` con: nombre, default, qué
  activa, archivo que la consume.
- La verificación es objetiva: `grep -rohE 'SWL_[A-Z_]+' hooks/ scripts/ |
  sort -u` debe ser un **subconjunto** del set de variables documentadas.
- **Sin excepciones**: variables internas de debug también se documentan
  (ej. `SWL_DEBUG`, `SWL_SESSION_ID`).

### Para ADRs

- Todo ADR nuevo `.planning/adrs/NNNN-*.md` que cambia comportamiento
  observable del sistema debe ser **referenciado** en al menos:
  - `MANUAL_USO.md` en la sección del feature que materializa, Y
  - `CHANGELOG.md` en la versión que lo introduce.
- ADRs de proceso interno (deprecaciones, splits internos, refactors
  ocultos) pueden documentarse solo en `.planning/adrs/README.md`.
- El criterio de "cambia comportamiento observable" se evalúa: ¿un usuario
  del sistema percibirá la diferencia? Si sí, debe ir a `MANUAL_USO.md`.

### Para integraciones opt-in (dependencias externas)

Toda dependencia externa opt-in (markitdown, code-review-graph,
agent-browser, @dbml/core, likec4, etc.) debe documentarse en
`MANUAL_USO.md § Dependencias externas` con la **estructura mínima**:

1. Marcador obligatorio "**NO es dependencia técnica de swl-ses**"
   (regla CLAUDE.md sobre dependencias educativas opt-in).
2. **Qué es** y **por qué existe la integración** (no solo
   instalación — eso es lo cosmético).
3. **Beneficio cuantificado** vs alternativas (tokens, espacio,
   tiempo, etc. — números, no adjetivos).
4. **Cuándo vale la pena** vs **cuándo NO instalarlo**.
5. **Cómo lo usa el sistema** internamente (qué agente, qué skill,
   qué comando lo invoca).
6. **Comportamiento si NO está instalado** (debe degradar
   funcionalmente sin fallar — regla `arreglar-al-detectar`).
7. **Limitaciones conocidas**.
8. **Origen** (ADR, sesión, paper, repo).

### Para prosa cuantificada en campos descriptivos de manifiestos JSON

Los campos `description` de `package.json` y `plugin.json` contienen prosa
con cifras agregadas del sistema (típicamente "60 agentes + N habilidades +
M comandos + K reglas + L hooks"). Esa prosa es **fuente de verdad parcial
para usuarios de npm y de Claude Code marketplace** — npm muestra el
description en la página del paquete; Claude Code lo lee al listar plugins.

Estos campos NO son agregados estructurales que los gates estándar
auditen (los gates escanean `.md` y comparan contra `INVENTARIO.md`),
por lo que necesitan tratamiento explícito:

1. **Universo a chequear**: `package.json#description` Y `plugin.json#description`.
   Ambos deben extraerse, parsearse para sus cifras, y compararse entre sí.

2. **Verificación cross-manifest**: las cifras de
   `package.json#description` deben coincidir letra por letra con las de
   `plugin.json#description`. Cualquier divergencia es bug de manifiesto
   inconsistente.

3. **Verificación vs fuente de verdad estructural**: las cifras de ambos
   manifiestos deben coincidir con los conteos reales que reporta
   `INVENTARIO.md` (regenerado por `node scripts/generar-inventario.js`).

4. **Gate automatizado**: `scripts/verificar-release.js` incluye gate
   "Gate de description" desde v1.6.4 que ejecuta exactamente esa
   triple validación. Confiar en su exit code antes de release.

**Anti-patrón documentado**: actualizar `plugin.json#description` con
cifras nuevas tras agregar 2 skills, asumir que `package.json#description`
está alineado por simetría, y commitear sin verificar. Origen del bug
v1.6.4 (sesión 2026-05-18): el commit del ADR-0028 actualizó
`plugin.json#description` (171/69/42 + ADR-0028) pero dejó
`package.json#description` con valores stale de v1.6.2 (162/67/41 +
ADR-0025). Los 4 gates pre-existentes no lo detectaron porque ninguno
escaneaba campos JSON descriptivos. El gate dedicado se agregó tras este
bug; la regla queda anti-recurrente.

---

## Procedimiento al ejecutar una auditoría documental

### Antes de reportar "verde"

1. **Listar qué mide cada check del verificador** y nombrar
   explícitamente qué **NO** mide.
2. **Hacer sondeo manual estructural** sobre 2-3 ítems aleatorios del
   dominio auditado:
   - Para comandos: tomar 2-3 al azar, contar menciones en MANUAL_USO,
     verificar que tengan las 6 subsecciones obligatorias.
   - Para variables: comparar lista de código (`grep -rohE`) contra
     lista de docs.
   - Para ADRs: cruzar `ls .planning/adrs/*.md` contra
     `grep -oE "ADR-[0-9]+" MANUAL_USO.md`.
3. **Reportar al usuario el desglose** entre:
   - Gate formal pasado: "N/N checks OK" (cita textual del verificador).
   - Drift estructural detectado en sondeo: "X gaps reales encontrados
     fuera del scope del verificador".

### Patrón de reporte correcto

```
Verificador docs-vs-código: 9/9 OK formal.
Sondeo estructural manual:
  - Comandos infra-documentados (<4 menciones): 3 detectados
    → /swl:exportar-vault, /swl:nemesis (en COMANDOS.md), /swl:wiki
  - Variables SWL_* huérfanas: 22 de 58
  - ADRs nuevos no referenciados en MANUAL_USO: 19 de 22

Conclusión: gate formal pasado, drift estructural REAL detectado.
Recomendación: cerrar gaps antes de declarar docs sanas.
```

### Patrón de reporte INCORRECTO (a evitar)

```
Verificador docs-vs-código: 9/9 OK.
Docs alineadas con código. ✓
```

Esta segunda forma es la que el usuario detectó y corrigió en
sesión 2026-05-16. **No reincidir**.

---

## Anti-patrones específicos del sistema SWL

- **Aceptar "WARN no falla el verificador"**: el check #2 actual
  reporta WARN sin bloquear cuando comandos no están documentados.
  Eso es deuda preexistente legítima, pero **NUNCA** se reporta como
  "OK" al usuario sin enumerar los WARN.
- **Confiar en el conteo agregado** (`44 comandos /swl:* documentados`)
  sin verificar la profundidad de cada uno.
- **No cruzar el universo real**: el verificador chequea `comandos/swl/*.md`
  contra `MANUAL_USO.md`. Pero NO chequea `MANUAL_USO.md` contra ADRs
  ni contra variables del código. Esos universos quedan invisibles.
- **Whitelist hardcodeada en check #3**: solo 7 flags críticas. El
  parser BOOLEANAS tiene más. Las flags no listadas en la whitelist
  son drift invisible.
- **Reportar "✓ skip" como "✓ pass"**: si el TUI no está instalado
  (pre-v1.6.0), el check #5 reporta éxito. Eso es correcto técnicamente
  pero el agente NO debe sumarlo al conteo "N/N OK" sin matizar.

---

## Relación con otras reglas

- `~/.claude/rules/arreglar-al-detectar.md § Aplicación a auditorías` —
  principio general; esta regla lo concreta para SWL.
- `~/.claude/rules/registro-componentes-nuevos.md` — define el registro
  obligatorio de componentes en manifiestos. Esta regla extiende:
  no basta con registrar, hay que documentarlo con profundidad.
- `~/.claude/rules/verificar-citas-normativas.md § Familia 2` —
  verificar afirmaciones factuales del verificador antes de aceptar
  el "verde" como hecho.
- `habilidades/doc-sync/SKILL.md` — implementación operativa del
  verificador. Esta regla define qué debe medir.

---

## Origen de esta regla

Sesión 2026-05-16, post-release v1.6.0. Documentado en
`.planning/adrs/0023-auditorias-documentales-estructurales.md`.
Promovida tras feedback explícito del usuario:
*"en esta misma sesión se pidieron dos auditorías que has minimizado o
ignorado"*. Cierra el gap conceptual donde el agente aplicaba
`arreglar-al-detectar.md` a bugs durante implementación pero NO a
verificadores de docs que devuelven verde cosmético.
