CreaRack-SL

Saneamiento de docs periódico · script audit + cron mensual

Vista limpiaEditar
ADRactivecreado Thu May 14#docs#audit#drift#ci#method

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:

  1. Es fácil de introducir (memoria humana + cambios constantes).
  2. Es difícil de detectar sin herramienta sistemática.
  3. 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).

CheckSeveridadQué detecta
wiki-countshardproduct: con valor desconocido (fuera de UI 5 wikis + huérfanas esperadas)
app-version-propagationhardAPP_VERSION no propagada a los 6 archivos donde debe (memoria feedback_version_bump_propagate)
dead-doc-refssoftReferencias Documentation/*.md que ya no existen (archivado abril 2026)
obsolete-bannerssoft.md con OBSOLETO/DEPRECATED en cuerpo sin banner explícito al inicio
ugly-bibask-slugssoftSlugs auto-generados feos del bib_ask (candidatos a Curator)
huerfanassoftPá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.py antes 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/infra requieren review humana caso a caso (reasignar a una wiki UI, archivar, o crear ruta nueva). Sub-iniciativa separada en TASK.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_PRODUCTS en 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:

  1. El cron mensual lleva 3 meses funcionando sin falsos positivos.
  2. Las 39 huérfanas están triadas y reasignadas/archivadas.
  3. 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 + workspace CLAUDE.md actualizados con conteos correctos.
  • ✅ Entry en TASK.md con 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]]

Referenciado desde

Inicio
Yo