Saneamiento de docs periódico · script audit + cron mensual
Contexto
Sesión 58 (12-05-2026) dejó memoria feedback_verified_closure tras detectar 4 ejemplos de drift documental acumulado entre planes/ADRs y la realidad del código: NEXT.md arrastraba PR2/3/4 cerrados durante 4 días, HELP_REBUILD_PLAN vigente con premisa muerta, ADR cleanup s55 declaraba “limpieza total” cubriendo solo CreaRack-Pro dejando 2 callers en workspace, types.ts seguía declarando env vars del proveedor retirado.
Sesión 61 (14-05-2026) reincidió con drift adicional: CLAUDE.md §7 listaba 4 wikis con 174 artículos cuando la realidad eran 5 wikis con 452 archivos. Tras corregir la tabla con un primer parser fallback (awk con head -20) el conteo resultó ser 227 páginas en CreaRack Help — pero el script audit definitivo reveló que el conteo correcto era 215. Es decir, el propio fix de drift introdujo nuevo drift que solo se detectó al implementar el script.
Esto demuestra que el drift documental:
- Es fácil de introducir (memoria humana + cambios constantes).
- Es difícil de detectar sin herramienta sistemática.
- Es caro de arrastrar (los 4 ejemplos s58 incluyeron una caída PROD de 25 min del Help Widget).
Decisión
Crear iniciativa periódica “saneamiento de docs” con 3 componentes:
1. Script scripts/audit_docs_drift.py
6 checks ejecutables on-demand o via cron. Vive en CreaRack-Pro porque tiene acceso a ambos repos (CreaRack-Pro + workspace clonado al lado).
| Check | Severidad | Qué detecta |
|---|---|---|
wiki-counts | hard | product: con valor desconocido (fuera de UI 5 wikis + huérfanas esperadas) |
app-version-propagation | hard | APP_VERSION no propagada a los 6 archivos donde debe (memoria feedback_version_bump_propagate) |
dead-doc-refs | soft | Referencias Documentation/*.md que ya no existen (archivado abril 2026) |
obsolete-banners | soft | .md con OBSOLETO/DEPRECATED en cuerpo sin banner explícito al inicio |
ugly-bibask-slugs | soft | Slugs auto-generados feos del bib_ask (candidatos a Curator) |
huerfanas | soft | Páginas con product: sin ruta UI (supercontext, infra) |
Exit code: 0 sin drift hard, 1 si drift hard, 2 error script.
2. Workflow .github/workflows/audit-docs-drift.yml
Cron 0 8 1-7 * 0 = primer domingo de cada mes 08:00 UTC (10:00 Madrid CEST / 09:00 CET). Evita coincidir con la routine STAGE crons (lunes 09:00 UTC).
Si exit code != 0 → abre issue automático con el reporte adjunto. Labels: audit, docs, auto-opened.
Coste estimado: ~3 min/mes contra cap GitHub Actions 3000 min (despreciable).
3. Auditoría manual al cierre de iniciativas grandes
Aplicable tras cerrar plan/ADR/fix grande (regla heurística s58):
- Ejecutar
audit_docs_drift.pyantes de declarar cerrado. - Aplicar checklist 6 puntos de
feedback_verified_closure: NEXT depurado, doc OBSOLETO con banner, scope explícito en ADRs cleanup, memorias actualizadas, worktrees stale eliminados, wiki alineada.
No-decisiones (qué NO hace esta iniciativa)
- No migra huérfanas automáticamente. Las 39 páginas con
product:supercontext/infrarequieren review humana caso a caso (reasignar a una wiki UI, archivar, o crear ruta nueva). Sub-iniciativa separada enTASK.md. - No edita docs automáticamente. El cron reporta drift, no lo corrige. Auto-actualizar docs vía cron es feo y propenso a feedback loops.
- No bloquea commits con drift soft. Solo hard (wiki-counts + app-version) son exit 1. Los 4 soft son informativos.
- No cubre drift fuera de docs. Para drift de código (callers AI hardcoded, env vars no migradas, etc.) se siguen usando audits puntuales por iniciativa.
Trade-offs aceptados
- False positive risk: si el equipo añade una wiki nueva (6ª) el script falla hard hasta actualizar
UI_PRODUCTSen el script. Mitigación: el mensaje de error explica qué hacer. - No cubre todos los formatos de drift posibles. Empezamos con 6 checks que cubren el 80% del drift histórico detectado. Más checks se añaden incrementalmente cuando aparezcan nuevos patrones.
- Cron mensual puede tardar 30 días en detectar drift recién introducido. Mitigación: ejecución manual al cierre de cada iniciativa grande + invocación on-demand desde dev local.
Criterio de éxito
La iniciativa queda operativa cuando:
- El cron mensual lleva 3 meses funcionando sin falsos positivos.
- Las 39 huérfanas están triadas y reasignadas/archivadas.
- El equipo lo ejecuta al cerrar cualquier sesión que toque docs (hábito incorporado).
Estado actual (14-05-2026)
- ✅ Script implementado y tested local.
- ✅ Workflow YAML creado (pendiente merge PR#29 CreaRack-Pro).
- ✅
CLAUDE.md§7 + workspaceCLAUDE.mdactualizados con conteos correctos. - ✅ Entry en
TASK.mdcon checklist y criterio de cierre. - ⏳ ADR (este documento) creado.
- ⏳ Sub-iniciativa 39 huérfanas (sesión dedicada).
Véase también
- [[feedback-verified-closure]]
- [[incident—20260512—help-widget-cf-access-s58]]
- [[feature—method—onboarding-v2]]