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:**
```bash
# 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:**
   ```bash
   grep -rn "ruta/antigua" --include="*.md" --include="*.ts"
   ```

2. **Crear mapeo de migración:**
   ```yaml
   mapeo:
     - antiguo: "/docs/ruta-vieja/"
       nuevo: "/docs/ruta-nueva/"
   ```

3. **Actualizar todas las referencias**

4. **Validar:**
   ```bash
   # 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:**
   ```markdown
   > ⚠️ **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:**
   ```markdown
   **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/

```yaml
# 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)

```yaml
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

```markdown
# [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

```markdown
## 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

```markdown
## 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

```bash
#!/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

```yaml
# .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:**
```bash
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:**
```bash
# 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