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)

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

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

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

# 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

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

6.2 Estructura Propuesta

# 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

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