Runbook: Audit Docs Drift — Ejecución, triaje y corrección de drift documental

Propósito

Este runbook cubre la operación del sistema de detección de drift documental introducido en PR#29 (s61). Está dirigido a cualquier miembro del equipo que reciba un issue automático del cron mensual o que quiera ejecutar el script manualmente al cierre de una sesión de desarrollo.

Cuándo ejecutar este runbook

Situación	Acción
Issue automático `[audit-docs-drift] Hard drift detectado` abierto por el cron	→ Sección Triaje de issue hard
Cierre de sesión que haya tocado docs (CLAUDE.md, TASK.md, wikis, CHANGELOG)	→ Sección Ejecución manual rápida
Añadir una nueva wiki (`product:` nuevo)	→ Sección Actualizar constantes del script
APP_VERSION bump	→ Sección Verificar propagación de versión
Smoke test tras merge de este PR	→ `gh workflow run audit-docs-drift.yml`

Prerequisitos

# Tener ambos repos clonados como hermanos:
# ├── CreaRack-Pro/          ← REPO_ROOT
# └── CreaRackSL-workspace/  ← WORKSPACE_ROOT

cd CreaRack-Pro
python --version  # ≥ 3.11

No hay dependencias externas — el script usa solo stdlib Python.

Ejecución manual rápida

# Desde la raíz de CreaRack-Pro:
python scripts/audit_docs_drift.py

Lectura del output:

## [OK] wiki-counts (hard)         → sin productos desconocidos ✓
## [OK] app-version-propagation (hard) → versión propagada en 6 archivos ✓
## [INFO] dead-doc-refs (soft)     → refs muertas (no bloquea)
## [INFO] huerfanas (soft)         → páginas sin ruta UI (no bloquea)
---
Summary: 0 hard failure(s), N soft info finding(s).

Exit code 0 → sin drift hard. Sin acción requerida.
Exit code 1 → drift hard detectado. Ver Triaje de issue hard.

Triaje de issue hard

1. `wiki-counts` falla

Causa típica: se añadió una página wiki con un product: no reconocido por el script.

Diagnóstico:

python scripts/audit_docs_drift.py --check wiki-counts --json | python -m json.tool
# Buscar "unknown_products" en el output

Resolución:

Caso	Acción
Nuevo `product:` para una wiki con ruta UI real	Añadir a `UI_PRODUCTS` en el script
Nuevo `product:` para páginas huérfanas esperadas	Añadir a `ORPHAN_PRODUCTS` en el script
Error tipográfico en front-matter de la página	Corregir el `product:` en el `.md` afectado

Tras corregir → re-ejecutar para confirmar status: ok.

2. `app-version-propagation` falla

Causa típica: APP_VERSION fue bumpeada en config/settings/base.py pero no se propagó a todos los archivos.

Diagnóstico:

python scripts/audit_docs_drift.py --check app-version-propagation --json
# Buscar "missing" en el output — lista archivos donde falta

Resolución:

# Ver la versión actual en settings:
grep "APP_VERSION" config/settings/base.py

# Buscar en cada archivo listado en "missing" y actualizar manualmente
# Archivos afectados: README.md, CLAUDE.md, pyproject.toml,
#   workspace/CLAUDE.md, workspace/src/components/shell/Sidebar.tsx,
#   workspace/src/components/variants/desktop/DesktopA.tsx

Si se añadieron nuevos archivos donde debe propagarse la versión → añadir a APP_VERSION_PROPAGATION en el script.

Triaje de findings soft (no bloquean, pero conviene revisar)

`dead-doc-refs`

Referencias Documentation/*.md que ya no existen. Mayoría serán entradas históricas del CHANGELOG (aceptables).

python scripts/audit_docs_drift.py --check dead-doc-refs --json

Acción por caso:

Referencia en CHANGELOG histórico → ignorar (aceptable).
Referencia en doc activo → actualizar la ruta o eliminar el enlace muerto.

`obsolete-banners`

Ficheros .md que mencionan OBSOLETO/DEPRECATED sin banner explícito al inicio.

python scripts/audit_docs_drift.py --check obsolete-banners

Acción: añadir al inicio del fichero afectado:

> **OBSOLETO**: Este documento ha sido reemplazado por [...].

`ugly-bibask-slugs`

~80 slugs patrón concept--general--existe-* generados por bib_ask sin curación. Candidatos a renombrar o archivar.

python scripts/audit_docs_drift.py --check ugly-bibask-slugs --json

Acción: sesión dedicada del Curator para renombrar, fusionar o archivar.

`huerfanas`

Páginas con product: supercontext o product: infra — sin ruta en la navegación UI.

python scripts/audit_docs_drift.py --check huerfanas --json

Acción por cada página (triaje caso a caso):

Reasignar product: a una wiki con ruta UI.
Crear ruta UI para ese producto.
Archivar si la página ya no tiene valor.

Estado actual (14-05-2026): 39 huérfanas (38 supercontext + 1 infra) — sub-iniciativa abierta en TASK.md.

Actualizar constantes del script

Nueva wiki con ruta UI

# En scripts/audit_docs_drift.py, línea ~45:
UI_PRODUCTS = {"crearack", "crearack-tech", "workspace", "workspace-tech", "ia-tech", "<nueva-wiki>"}

Nueva ruta de propagación de APP_VERSION

# En scripts/audit_docs_drift.py, línea ~50:
APP_VERSION_PROPAGATION = [
    ...
    REPO_ROOT / "ruta/al/nuevo/archivo.ext",
]

Tras editar: ejecutar python scripts/audit_docs_drift.py para confirmar que los checks pasan.

Verificar el workflow CI

# Disparar manualmente (requiere gh CLI autenticado):
gh workflow run audit-docs-drift.yml

# Ver estado del último run:
gh run list --workflow=audit-docs-drift.yml --limit=5

# Descargar el artifact de reporte:
gh run download <RUN_ID> --name docs-drift-report

El artifact docs-drift-report se retiene 90 días.

Formato del issue automático

Cuando hay drift hard, el workflow crea un issue con:

Título: [audit-docs-drift] Hard drift detectado · YYYY-MM-DD
Labels: audit, docs, auto-opened
Body: reporte markdown completo (truncado a 60.000 chars si es muy largo).

Cerrar el issue solo tras confirmar que el check pasa en re-ejecución manual.

Véase también

[[feature—ci—audit-docs-drift]]
[[decision—20260514—saneamiento-docs-periodico]]