workspace-v1/orchestration/analisis/C3-PROTOCOLO-MANTENIMIENTO-DOCUMENTACION-2026-01-10.md

C3: Protocolo de Mantenimiento de Documentación

Fecha: 2026-01-10 Versión: 1.0 Aplicable a: Proyecto Gamilit + Sistema NEXUS + Sistema SIMCO Objetivo: Prevenir desincronización y mantener coherencia documental

---

1. Estructura de Gobernanza

1.1 Responsabilidades por Capa

Capa	Responsable	Documentación
Database	NEXUS-DATABASE	/docs/90-transversal/inventarios-database/
Backend	NEXUS-BACKEND	DTOs, entities, API specs
Frontend	NEXUS-FRONTEND	Types, componentes, UI specs
Integración	NEXUS-INTEGRATION	Validación cruzada, reportes
DevOps	NEXUS-DEVOPS	Deployment, CI/CD docs
Workspace	SIMCO	/orchestration/directivas/

1.2 Jerarquía Documental

Nivel 0: SIMCO (Workspace)
  └── /orchestration/
      ├── directivas/simco/       # Directivas globales
      ├── agents/perfiles/         # Perfiles de agentes
      └── inventarios/             # Inventarios de entorno

Nivel 1: NEXUS (Proyecto Gamilit)
  └── /projects/gamilit/.claude/
      ├── agents/                  # Agentes especializados
      ├── directivas/              # Directivas de proyecto
      └── orchestration/           # Estado y trazas

Nivel 2: Documentación Técnica
  └── /projects/gamilit/docs/
      ├── 01-fase-alcance-inicial/ # Requerimientos
      ├── 90-transversal/          # Specs técnicas
      ├── 95-guias-desarrollo/     # Guías dev
      └── planning/                # Planificación

---

2. Validaciones Periódicas

2.1 Validación Diaria (Automática)

Ejecutar: Al inicio de cada sesión de desarrollo

Checklist:

• Rutas referenciadas existen en filesystem
• No hay archivos huérfanos (sin referencias)
• Imports/exports funcionan correctamente

Comando sugerido:

# Verificar rutas /docs/ en .claude/
grep -rn "docs/" projects/gamilit/.claude/ | \
  awk -F':' '{print $3}' | \
  grep -oP '/docs/[^)\"]+' | \
  sort -u | \
  while read path; do
    [ -e "projects/gamilit$path" ] || echo "FALTA: $path"
  done

2.2 Validación Semanal

Ejecutar: Fin de cada sprint

Checklist:

• Coherencia DB → Backend (objetivo: 95%+)
• Coherencia Backend → Frontend (objetivo: 75%+)
• Type Safety E2E (objetivo: 85%+)
• Nuevos DTOs tienen tipos frontend correspondientes
• Nuevas tablas tienen entities correspondientes

Agente responsable: NEXUS-INTEGRATION

2.3 Auditoría Mensual

Ejecutar: Primer día de cada mes

Checklist:

• Revisión de archivos DEPRECADOS (eliminar si >30 días)
• Actualización de fechas en documentos versionados
• Limpieza de reportes de análisis antiguos
• Verificación de cross-references entre sistemas
• Actualización de inventarios

---

3. Procesos de Cambio

3.1 Al Agregar Nueva Funcionalidad

Flujo:

1. NEXUS-DATABASE
   → Crear migration
   → Actualizar /docs/90-transversal/inventarios-database/

2. NEXUS-BACKEND
   → Crear entities/DTOs
   → Verificar coherencia con DB
   → Actualizar API specs si aplica

3. NEXUS-FRONTEND
   → Crear types correspondientes
   → Actualizar componentes
   → Verificar coherencia con Backend

4. NEXUS-INTEGRATION
   → Validar coherencia 3 capas
   → Generar reporte
   → Actualizar métricas en _MAP.md

3.2 Al Reestructurar Documentación

OBLIGATORIO antes de mover/renombrar:

1. Buscar referencias:

   grep -rn "ruta/antigua" --include="*.md" --include="*.ts"
   

2. Crear mapeo de migración:

   mapeo:
     - antiguo: "/docs/ruta-vieja/"
       nuevo: "/docs/ruta-nueva/"
   

3. Actualizar todas las referencias

4. Validar:

   # No deben quedar referencias antiguas
   grep -rn "ruta/antigua" --include="*.md" | wc -l
   # Debe ser 0
   

5. Documentar cambio en archivo de análisis

3.3 Al Deprecar Archivos

Proceso:

1. Agregar header de deprecación:

   > ⚠️ **DEPRECADO** - Este archivo está DEPRECADO desde YYYY-MM-DD.
   > **Usar en su lugar:** `nuevo-archivo.md`
   > **Motivo:** [Explicación breve]
   

2. Agregar cross-reference al nuevo archivo:

   **Nota:** Este archivo reemplaza a `archivo-deprecado.md`
   

3. Mantener archivo 30 días antes de eliminar

4. Actualizar inventarios que lo referencien

---

4. Estructura de Rutas Canónica

4.1 Mapeo Oficial de /docs/

# Este es el mapeo oficial - NO usar otras rutas
rutas_canonicas:
  requerimientos: "/docs/01-fase-alcance-inicial/"
  robustecimiento: "/docs/02-fase-robustecimiento/"
  extensiones: "/docs/03-fase-extensiones/"
  backlog: "/docs/04-fase-backlog/"

  especificaciones: "/docs/90-transversal/"
  apis: "/docs/90-transversal/api/"
  database: "/docs/90-transversal/inventarios-database/"
  arquitectura: "/docs/90-transversal/arquitectura/"
  ssot: "/docs/90-transversal/ssot/"

  guias: "/docs/95-guias-desarrollo/"
  quick_ref: "/docs/96-quick-reference/"
  adr: "/docs/97-adr/"
  troubleshooting: "/docs/99-troubleshooting/"

  planning: "/docs/planning/"
  audits: "/docs/audits/"
  archivados: "/docs/archivados/"

4.2 Rutas Prohibidas (NO USAR)

rutas_obsoletas:
  - "/docs/01-requerimientos/"      # Usar 01-fase-alcance-inicial
  - "/docs/02-especificaciones/"    # Usar 90-transversal
  - "/docs/03-desarrollo/"          # Usar 95-guias-desarrollo
  - "/docs/04-planificacion/"       # Usar planning
  - "/docs/standards/"              # Usar 95-guias-desarrollo
  - "/docs/adr/"                    # Usar 97-adr
  - "/docs/00-overview/"            # Usar 00-vision-general

---

5. Métricas de Salud Documental

5.1 KPIs Objetivo

Métrica	Mínimo	Objetivo	Crítico
Coherencia DB→Backend	90%	95%	<85%
Coherencia Backend→Frontend	70%	85%	<50%
Type Safety E2E	80%	90%	<60%
Rutas válidas	98%	100%	<95%
Archivos deprecados	<5	0	>10
Docs sin actualizar (>90 días)	<10%	<5%	>20%

5.2 Dashboard de Métricas

Ubicación: .claude/orchestration/05-validaciones/_MAP.md

Actualizar con cada validación:

• Total discrepancias
• Coverage por capa
• Fecha última validación
• Issues P0/P1/P2 abiertos

---

6. Plantillas Estándar

6.1 Header de Documento

# [Título del Documento]

**Versión:** X.Y
**Fecha:** YYYY-MM-DD
**Última actualización:** YYYY-MM-DD
**Autor/Agente:** [nombre]
**Estado:** BORRADOR | REVISIÓN | APROBADO | DEPRECADO

---

6.2 Registro de Cambios

## Historial de Cambios

| Versión | Fecha | Autor | Descripción |
|---------|-------|-------|-------------|
| 1.0 | 2026-01-10 | NEXUS-X | Versión inicial |
| 1.1 | 2026-02-15 | NEXUS-Y | Actualización X |

6.3 Cross-Reference

## Documentos Relacionados

- **Padre:** [documento-padre.md](ruta)
- **Relacionados:**
  - [doc-1.md](ruta) - Descripción
  - [doc-2.md](ruta) - Descripción
- **Reemplaza a:** [doc-deprecado.md](ruta) (DEPRECADO)

---

7. Automatización Recomendada

7.1 Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

# Verificar rutas en archivos .claude/
INVALID_PATHS=$(grep -rn "docs/0[1-4]-" projects/gamilit/.claude/ 2>/dev/null | head -5)
if [ -n "$INVALID_PATHS" ]; then
  echo "ERROR: Rutas obsoletas detectadas:"
  echo "$INVALID_PATHS"
  echo "Usar rutas canónicas (ver PROTOCOLO-MANTENIMIENTO)"
  exit 1
fi

# Verificar headers de deprecación tienen fecha
MISSING_DATE=$(grep -rn "DEPRECADO" projects/gamilit/.claude/ | grep -v "desde" | head -3)
if [ -n "$MISSING_DATE" ]; then
  echo "WARNING: Archivos deprecados sin fecha:"
  echo "$MISSING_DATE"
fi

7.2 CI Pipeline Check

# .github/workflows/docs-validation.yml
name: Documentation Validation

on:
  pull_request:
    paths:
      - 'projects/gamilit/.claude/**'
      - 'projects/gamilit/docs/**'
      - 'orchestration/**'

jobs:
  validate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Check deprecated paths
        run: |
          if grep -rn "docs/01-requerimientos\|docs/02-especificaciones\|docs/03-desarrollo\|docs/04-planificacion" projects/gamilit/.claude/; then
            echo "::error::Deprecated paths found"
            exit 1
          fi          

      - name: Check orphan references
        run: |
          ./scripts/check-orphan-refs.sh          

---

8. Resolución de Problemas Comunes

8.1 Ruta No Existe

Síntoma: Referencia a /docs/X/ pero directorio no existe

Diagnóstico:

ls -la projects/gamilit/docs/

Solución:

1. Verificar mapeo canónico (Sección 4.1)
2. Actualizar referencia a ruta correcta
3. Si es nueva ruta, crear directorio con README

8.2 Archivo Duplicado

Síntoma: Dos archivos con contenido similar

Diagnóstico:

1. Comparar fechas de modificación
2. Verificar cuál tiene más referencias
3. Determinar cuál es más completo

Solución:

1. Consolidar contenido en archivo más actualizado
2. Deprecar archivo antiguo con cross-reference
3. Actualizar todas las referencias

8.3 Coherencia Baja Backend→Frontend

Síntoma: Score <50% en validación

Diagnóstico:

# Listar DTOs sin tipos frontend
grep -rn "export class.*Dto" apps/backend/src/ | \
  awk -F':' '{print $1}' | \
  sort -u > /tmp/backend-dtos.txt

grep -rn "export interface\|export type" apps/frontend/src/shared/types/ | \
  awk -F':' '{print $1}' | \
  sort -u > /tmp/frontend-types.txt

# Comparar
diff /tmp/backend-dtos.txt /tmp/frontend-types.txt

Solución:

1. Priorizar por uso (endpoints más usados primero)
2. Crear tipos siguiendo guía C2
3. Validar después de cada batch

---

9. Calendario de Mantenimiento

Diario

• Verificación rápida de rutas al iniciar sesión

Semanal (Viernes)

• Ejecutar validación NEXUS-INTEGRATION
• Revisar issues P0 abiertos
• Actualizar _MAP.md con métricas

Mensual (Día 1)

• Auditoría completa de documentación
• Limpieza de archivos deprecados (>30 días)
• Revisión de KPIs vs objetivos
• Planificación de mejoras

Trimestral

• Revisión estructural de /docs/
• Actualización de este protocolo si necesario
• Capacitación de equipo en cambios

---

10. Contacto y Escalación

Para Issues de Documentación

1. Nivel 1: Corregir localmente siguiendo este protocolo
2. Nivel 2: Consultar con NEXUS-INTEGRATION
3. Nivel 3: Escalar a Documentation-Architect

Para Issues de Coherencia Código

1. Nivel 1: Agente responsable de capa
2. Nivel 2: NEXUS-INTEGRATION para validación cruzada
3. Nivel 3: Reunión de sincronización multi-agente

---

Documentado por: Documentation-Architect (Fase C3) Fecha: 2026-01-10 Próxima revisión: 2026-04-10