workspace-v1/orchestration/analisis/ANALISIS-DIRECTIVA-MANTENIMIENTO-DOCUMENTACION-2026-01-10.md

# ANÁLISIS - DIRECTIVA DE MANTENIMIENTO Y PURGA DE DOCUMENTACIÓN
**Fecha:** 2026-01-10
**Fase:** 1 - Análisis Inicial
**Estado:** EN PROGRESO
**Solicitante:** Usuario
**Tipo:** Nueva Directiva SIMCO

---

## 1. PROBLEMA IDENTIFICADO

### 1.1 Descripción del Problema

Cuando se trabaja intensamente sobre un proyecto:
1. La documentación se actualiza frecuentemente
2. Con el tiempo se generan **conflictos** entre versiones
3. Documentación **obsoleta** permanece mezclada con la vigente
4. Los agentes/subagentes **pierden contexto** al compactar conversaciones
5. No hay un **ciclo sistemático** de depuración documental
6. Las **dependencias** entre documentos no se validan tras cambios

### 1.2 Síntomas Observados

| Síntoma | Impacto | Frecuencia |
|---------|---------|------------|
| Docs desactualizados post-implementación | Alto | Frecuente |
| Conflictos entre specs y código | Alto | Frecuente |
| Históricos obsoletos sin deprecar | Medio | Muy frecuente |
| Pérdida de contexto en subagentes | Alto | Siempre |
| Dependencias rotas entre docs | Medio | Frecuente |
| Scripts BD desincronizados con DDL | Crítico | Ocasional |

### 1.3 Causa Raíz

```
CICLO ACTUAL (INCOMPLETO):
Tarea → Implementación → [Documentación Opcional] → Cierre

PROBLEMA:
- No hay fase obligatoria de SINCRONIZACIÓN documental
- No hay fase de DEPRECACIÓN de históricos
- No hay VALIDACIÓN de dependencias documentales
- Subagentes no consultan directivas automáticamente
```

---

## 2. REQUISITOS DE LA SOLUCIÓN

### 2.1 Requisitos Funcionales (del Usuario)

| ID | Requisito | Prioridad |
|----|-----------|-----------|
| RF-01 | Purga gradual de documentación tras cada tarea/fase | P0 |
| RF-02 | Deprecación sistemática de históricos obsoletos | P0 |
| RF-03 | Actualización obligatoria de docs al completar tarea | P0 |
| RF-04 | Validación de dependencias (docs ↔ código ↔ BD) | P0 |
| RF-05 | Scripts BD sincronizados con cambios DDL | P0 |
| RF-06 | Análisis de objetos dependientes y dependencias | P0 |
| RF-07 | Agentes consulten directivas automáticamente | P0 |
| RF-08 | Fases: Análisis → Plan → Validación → Refinamiento → Ejecución → Validación | P0 |

### 2.2 Requisitos de los Prompts de Referencia

**Prompt 1 - Sincronización BD:**
```
- Documentar cambios con estándares
- Actualizar scripts create/recreate database
- Ejecutar recreación para validar
- Analizar objetos modificados
- Validar dependencias (dependientes + de los que depende)
- Actualizar BD, backend y frontend si requerido
```

**Prompt 2 - Integración Docs → Desarrollo:**
```
- Análisis detallado de cambios en docs
- Validar integración correcta al desarrollo
- Separar tareas con máximo detalle
- Fases completas de validación
- Comparación completa y detallada
```

### 2.3 Requisitos de Integración

| Integración | Descripción |
|-------------|-------------|
| CAPVED | Insertar fase de mantenimiento documental en ciclo |
| SIMCO-DOCUMENTAR | Extender con validación de dependencias |
| SIMCO-DDL | Integrar sincronización con scripts |
| Subagentes | Carga automática de directivas relevantes |
| Inventarios | Actualización post-cambios |

---

## 3. ANÁLISIS DE CICLO DE VIDA DOCUMENTAL

### 3.1 Ciclo Actual (CAPVED)

```
C - Contexto      → Cargar docs existentes
A - Análisis      → Analizar problema
P - Plan          → Planificar solución
V - Validación    → Validar plan
E - Ejecución     → Implementar
D - Documentación → [Débil] Documentar cambios
```

**Problema:** La fase D (Documentación) es débil y no incluye:
- Validación de consistencia
- Purga de obsoletos
- Sincronización de dependencias
- Actualización de scripts

### 3.2 Ciclo Propuesto (CAPVED + M)

```
C - Contexto      → Cargar docs + directivas obligatorias
A - Análisis      → Analizar problema + impacto documental
P - Plan          → Planificar solución + cambios docs
V - Validación    → Validar plan + dependencias
E - Ejecución     → Implementar + actualizar docs en paralelo
D - Documentación → Documentar + sincronizar + validar
M - Mantenimiento → Purgar + deprecar + verificar integridad [NUEVO]
```

### 3.3 Fase M - Mantenimiento (Detalle)

```yaml
FASE_M_MANTENIMIENTO:
  paso_1_identificacion:
    - Identificar docs modificados en la tarea
    - Identificar docs relacionados (dependencias)
    - Identificar históricos potencialmente obsoletos

  paso_2_sincronizacion:
    - Sincronizar specs ↔ código
    - Sincronizar DDL ↔ scripts BD
    - Sincronizar inventarios ↔ realidad
    - Sincronizar frontend ↔ backend ↔ BD

  paso_3_validacion_dependencias:
    - Validar objetos dependientes actualizados
    - Validar objetos de los que se depende
    - Validar referencias cruzadas
    - Ejecutar scripts de validación

  paso_4_deprecacion:
    - Marcar docs obsoletos con [DEPRECATED]
    - Mover a carpeta 99-archivo/ si aplica
    - Actualizar _MAP.md con estado
    - Registrar en changelog

  paso_5_purga_gradual:
    - Eliminar secciones redundantes
    - Consolidar información duplicada
    - Reducir verbosidad manteniendo esencia
    - Actualizar fechas y versiones

  paso_6_verificacion_final:
    - Ejecutar checklist de integridad
    - Validar build/lint/test
    - Confirmar scripts BD ejecutables
    - Documentar estado final
```

---

## 4. ANÁLISIS DE DEPENDENCIAS DOCUMENTALES

### 4.1 Tipos de Dependencias

```
DEPENDENCIAS VERTICALES (Jerárquicas):
├── Visión/Roadmap
│   └── Épicas
│       └── Historias de Usuario
│           └── Especificaciones Técnicas
│               └── Código Implementado

DEPENDENCIAS HORIZONTALES (Entre Capas):
├── DDL (schemas) ↔ Entities (backend) ↔ Types (frontend)
├── API Specs ↔ Controllers ↔ Services ↔ Repositories
├── Inventarios ↔ Código real ↔ Documentación

DEPENDENCIAS DE SCRIPTS:
├── DDL files ↔ create-database.sh
├── Seeds ↔ seed-database.sh
├── Migrations ↔ migrate.sh
```

### 4.2 Matriz de Impacto de Cambios

| Cambio en | Impacta a |
|-----------|-----------|
| DDL (tabla) | Entity, DTO, Repository, Service, Controller, API Spec, Frontend Types, Tests, Inventario BD |
| Entity | DTO, Service, Tests, Inventario Backend |
| API Endpoint | Frontend Service, Tests, API Spec, Inventario Backend |
| Componente UI | Tests, Inventario Frontend |
| Configuración | Docs de setup, Environment vars, Inventarios |

### 4.3 Validación de Dependencias Requerida

```yaml
VALIDACION_DEPENDENCIAS:
  al_modificar_ddl:
    - [ ] Entity actualizada
    - [ ] DTO actualizado
    - [ ] Repository actualizado
    - [ ] Service actualizado (si métodos afectados)
    - [ ] Controller actualizado (si endpoints afectados)
    - [ ] Tests actualizados
    - [ ] Script create-database.sh actualizado
    - [ ] Inventario DATABASE_INVENTORY actualizado
    - [ ] Ejecutar recreación de BD exitosa

  al_modificar_backend:
    - [ ] DTOs consistentes con entities
    - [ ] Tests actualizados
    - [ ] API Spec/Swagger actualizado
    - [ ] Frontend types actualizados (si API cambió)
    - [ ] Inventario BACKEND_INVENTORY actualizado

  al_modificar_frontend:
    - [ ] Types consistentes con API
    - [ ] Tests actualizados
    - [ ] Inventario FRONTEND_INVENTORY actualizado

  al_modificar_docs:
    - [ ] _MAP.md actualizado
    - [ ] Referencias cruzadas válidas
    - [ ] Versiones incrementadas
    - [ ] Fechas actualizadas
```

---

## 5. ANÁLISIS DE CARGA DE CONTEXTO PARA AGENTES

### 5.1 Problema Actual

```
PROBLEMA:
- Subagentes inician sin contexto de directivas
- Al compactar conversaciones se pierde el "cómo hacer"
- Cada agente debe ser instruido manualmente
- No hay carga automática de estándares relevantes
```

### 5.2 Solución Propuesta: Contexto Obligatorio por Operación

```yaml
CONTEXTO_OBLIGATORIO:
  cualquier_tarea:
    - @TAREA
    - @CAPVED
    - @HERENCIA_SIMCO (del proyecto)

  operacion_ddl:
    - @OP_DDL
    - @MIGRACIONES
    - @INVENTARIOS
    - @MANTENIMIENTO_DOCS [NUEVO]

  operacion_backend:
    - @OP_BACKEND
    - @TESTING
    - @INVENTARIOS
    - @MANTENIMIENTO_DOCS [NUEVO]

  operacion_frontend:
    - @OP_FRONTEND
    - @TESTING
    - @INVENTARIOS
    - @MANTENIMIENTO_DOCS [NUEVO]

  operacion_documentacion:
    - @DOC_PROYECTO
    - @NOMENCLATURA
    - @ESTRUCTURA_DOCS
    - @MANTENIMIENTO_DOCS [NUEVO]

  integracion_externa:
    - @INTEGRACIONES
    - @MANTENIMIENTO_DOCS [NUEVO]
```

### 5.3 Mecanismo de Carga Automática

```yaml
# Propuesta: Sección en HERENCIA-SIMCO.md de cada proyecto
CARGA_AUTOMATICA_CONTEXTO:
  nivel: OBLIGATORIO
  directivas_base:
    - workspace/orchestration/directivas/simco/SIMCO-TAREA.md
    - workspace/orchestration/directivas/principios/PRINCIPIO-CAPVED.md
    - proyecto/orchestration/00-guidelines/HERENCIA-SIMCO.md

  directivas_por_operacion:
    ddl: [@OP_DDL, @MIGRACIONES, @MANTENIMIENTO_DOCS]
    backend: [@OP_BACKEND, @TESTING, @MANTENIMIENTO_DOCS]
    frontend: [@OP_FRONTEND, @TESTING, @MANTENIMIENTO_DOCS]
    docs: [@DOC_PROYECTO, @NOMENCLATURA, @MANTENIMIENTO_DOCS]

  instruccion_subagentes: |
    ANTES de ejecutar cualquier tarea:
    1. Cargar directivas base
    2. Identificar tipo de operación
    3. Cargar directivas específicas de operación
    4. Consultar HERENCIA-SIMCO.md del proyecto
    5. Aplicar ciclo CAPVED completo incluyendo fase M    
```

---

## 6. PROPUESTA DE DIRECTIVA

### 6.1 Nombre y Alias

```yaml
nombre: SIMCO-MANTENIMIENTO-DOCUMENTACION.md
alias: @MANTENIMIENTO_DOCS
version: 1.0.0
categoria: operaciones_documentacion
obligatoria: true
```

### 6.2 Estructura Propuesta

```markdown
# SIMCO-MANTENIMIENTO-DOCUMENTACION

## 1. Propósito
## 2. Cuándo Aplicar (Triggers)
## 3. Ciclo de Mantenimiento (6 pasos)
## 4. Validación de Dependencias
## 5. Sincronización BD ↔ Docs ↔ Código
## 6. Protocolo de Deprecación
## 7. Purga Gradual
## 8. Checklist de Cierre
## 9. Integración con CAPVED
## 10. Carga de Contexto para Subagentes
```

### 6.3 Artefactos Adicionales Requeridos

| Artefacto | Tipo | Propósito |
|-----------|------|-----------|
| CHECKLIST-MANTENIMIENTO-DOCS.md | Checklist | Validar mantenimiento completo |
| CHECKLIST-SINCRONIZACION-BD.md | Checklist | Validar sincronización BD |
| TEMPLATE-DEPRECACION.md | Template | Marcar docs deprecados |
| FLUJO-VALIDACION-DEPENDENCIAS.md | Guía | Proceso de validación |

---

## 7. MÉTRICAS DE ÉXITO

### 7.1 Objetivos Medibles

| Métrica | Objetivo | Medición |
|---------|----------|----------|
| Docs obsoletos sin deprecar | 0 | Auditoría mensual |
| Conflictos docs ↔ código | < 5% | Por sprint |
| Scripts BD sincronizados | 100% | Por cambio DDL |
| Dependencias rotas | 0 | Por release |
| Subagentes con contexto | 100% | Por delegación |

### 7.2 Indicadores de Adopción

```yaml
indicadores:
  - Uso de @MANTENIMIENTO_DOCS en tareas
  - Ejecución de CHECKLIST-MANTENIMIENTO-DOCS
  - Documentos deprecados correctamente
  - Scripts BD validados post-cambio
  - Inventarios actualizados
```

---

## 8. PLAN DE FASES

### Fase 2: Análisis Detallado
- Revisar directivas existentes relacionadas
- Mapear integraciones necesarias
- Definir flujos detallados

### Fase 3: Planificación
- Diseñar estructura de SIMCO-MANTENIMIENTO-DOCUMENTACION
- Diseñar checklists y templates
- Definir integración con CAPVED

### Fase 4: Validación del Plan
- Validar contra requisitos RF-01 a RF-08
- Validar integración con directivas existentes
- Validar cobertura de prompts de referencia

### Fase 5: Refinamiento
- Ajustar según validación
- Optimizar flujos
- Simplificar donde sea posible

### Fase 6: Ejecución
- Crear SIMCO-MANTENIMIENTO-DOCUMENTACION.md
- Crear checklists
- Crear templates
- Actualizar INDICE-DIRECTIVAS-WORKSPACE.yml

### Fase 7: Validación Final
- Verificar todos los artefactos
- Probar en proyecto piloto
- Documentar resultado

---

## 9. SIGUIENTE PASO

**Proceder a Fase 2: Análisis Detallado**

Tareas:
1. Revisar SIMCO-DOCUMENTAR.md existente
2. Revisar PRINCIPIO-CAPVED.md
3. Revisar flujos de delegación a subagentes
4. Mapear todos los puntos de integración

---

**Estado:** FASE 1 COMPLETADA
**Siguiente:** Fase 2 - Análisis Detallado
**Fecha:** 2026-01-10