workspace-v1/orchestration/directivas/principios/PRINCIPIO-CAPVED.md

PRINCIPIO: CAPVED - Ciclo de Vida de Tareas

Versión: 1.0.0 Fecha: 2025-12-08 Tipo: Principio Fundamental - HERENCIA OBLIGATORIA Aplica a: TODOS los agentes sin excepción

---

DECLARACIÓN DEL PRINCIPIO

╔══════════════════════════════════════════════════════════════════════════════╗
║                                                                               ║
║    CAPVED: Contexto → Análisis → Planeación → Validación → Ejecución → Doc   ║
║                                                                               ║
║    "Toda tarea que modifica código o documentación DEBE pasar por            ║
║     el ciclo completo CAPVED antes de considerarse Done."                    ║
║                                                                               ║
║    "Si aparece trabajo fuera del alcance original, se genera HU nueva."      ║
║                                                                               ║
╚══════════════════════════════════════════════════════════════════════════════╝

---

QUÉ ES CAPVED

CAPVED es un ciclo de vida obligatorio para toda Historia de Usuario (HU) o tarea técnica que involucre modificación de código o documentación. Garantiza:

1. Trazabilidad completa: Desde el origen hasta la implementación
2. Análisis de impacto: Antes de tocar código
3. Validación de coherencia: Plan vs Análisis
4. Generación controlada: HUs derivadas para descubrimientos
5. Documentación actualizada: Como criterio de Done

---

LAS 6 FASES DE CAPVED

┌─────────────────────────────────────────────────────────────────────────────┐
│  C - CONTEXTO                                                                │
│  • Vincular HU a proyecto/módulo/epic                                       │
│  • Clasificar tipo: feature | fix | refactor | spike | doc-only             │
│  • Registrar origen: plan-original | descubrimiento | incidencia            │
│  • Cargar documentos SIMCO relevantes                                       │
├─────────────────────────────────────────────────────────────────────────────┤
│                                    ↓                                         │
├─────────────────────────────────────────────────────────────────────────────┤
│  A - ANÁLISIS                                                                │
│  • Comportamiento deseado (perspectiva de negocio)                          │
│  • Restricciones: seguridad, performance, UX                                │
│  • Objetos impactados: BD, Backend, Frontend, otros proyectos               │
│  • Dependencias con otras HUs (bloquea/bloqueada por)                       │
│  • Riesgos identificados                                                    │
│  → SALIDA: Lista de objetos + dependencias + riesgos                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                    ↓                                         │
├─────────────────────────────────────────────────────────────────────────────┤
│  P - PLANEACIÓN                                                              │
│  • Desglose en subtareas por dominio (BD, BE, FE, Docs)                     │
│  • Orden de ejecución y dependencias                                        │
│  • Criterios de aceptación por subtarea                                     │
│  • Plan de pruebas: unitarias, integración, regresión                       │
│  • Asignación de agentes/subagentes                                         │
│  → SALIDA: Plan de ejecución con subtareas asignadas                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                    ↓                                         │
├─────────────────────────────────────────────────────────────────────────────┤
│  V - VALIDACIÓN (⚠️ NO DELEGAR - EJECUTAR DIRECTAMENTE)                     │
│  • ¿Todo lo detectado en A tiene acción concreta en P?                      │
│  • ¿Hay dependencias ocultas sin atender?                                   │
│  • ¿Criterios de aceptación cubren los riesgos?                             │
│  • ¿Hay scope creep? → Registrar y crear HU derivada                        │
│  → GATE: Solo pasa a Ejecución si todo cuadra                               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                    ↓                                         │
├─────────────────────────────────────────────────────────────────────────────┤
│  E - EJECUCIÓN                                                               │
│  • Actualizar docs/ del proyecto PRIMERO                                    │
│  • Ejecutar subtareas en orden establecido                                  │
│  • Cada subtarea: código + notas + validación (build/lint)                  │
│  • Registrar progreso y desviaciones                                        │
│  → USAR: SIMCO correspondientes (CREAR, MODIFICAR, DDL, etc.)               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                    ↓                                         │
├─────────────────────────────────────────────────────────────────────────────┤
│  D - DOCUMENTACIÓN CONTINUA                                                  │
│  • Actualizar diagramas y modelos de dominio                                │
│  • Actualizar especificaciones técnicas (BD, APIs, contratos)               │
│  • Crear/actualizar ADRs si hubo decisiones arquitectónicas                 │
│  • Actualizar inventarios (DATABASE, BACKEND, FRONTEND)                     │
│  • Actualizar trazas de tareas                                              │
│  • Registrar HUs derivadas (si se generaron)                                │
│  • Registrar lecciones aprendidas                                           │
│  → GATE: HU NO está Done si documentación no está actualizada               │
└─────────────────────────────────────────────────────────────────────────────┘

---

CUÁNDO APLICA CAPVED

APLICA A (Obligatorio):

Tareas_que_DEBEN_seguir_CAPVED:
  - Nuevas features (cualquier tamaño)
  - Bug fixes que modifican código
  - Refactorizaciones
  - Cambios en estructura de BD
  - Nuevos endpoints de API
  - Nuevos componentes de UI
  - Cambios en lógica de negocio
  - Integraciones con sistemas externos
  - Cualquier tarea que genere commit

NO APLICA A (Excepciones):

Tareas_exentas_de_CAPVED_completo:
  - Corrección de typos en código (solo E+D)
  - Actualización de dependencias menores (solo E+D)
  - Tareas puramente exploratorias (solo lectura)
  - Consultas de información
  - Spikes de investigación sin implementación

NOTA: Incluso las excepciones DEBEN documentar en trazas

---

INTEGRACIÓN CON SIMCO

CAPVED es el ciclo de vida, SIMCO son las operaciones:

CAPVED                          SIMCO
───────                         ─────
C - Contexto          →         SIMCO-INICIALIZACION.md (CCA)
A - Análisis          →         SIMCO-BUSCAR.md + docs/
P - Planeación        →         TEMPLATE-PLAN.md
V - Validación        →         Checklist CAPVED (este documento)
E - Ejecución         →         SIMCO-CREAR/MODIFICAR/DDL/BACKEND/FRONTEND
D - Documentación     →         SIMCO-DOCUMENTAR.md + inventarios + trazas

Orden de Lectura para Agentes:

1. SIMCO-INICIALIZACION.md      # Bootstrap con CCA
2. PRINCIPIO-CAPVED.md          # Este documento (ciclo obligatorio)
3. PRINCIPIO-DOC-PRIMERO.md     # Documentación antes de código
4. PRINCIPIO-ANTI-DUPLICACION.md # Verificar antes de crear
5. PRINCIPIO-VALIDACION-OBLIGATORIA.md # Build/lint obligatorios
6. SIMCO-TAREA.md               # Proceso detallado CAPVED
7. SIMCO específicos según operación

---

GENERACIÓN DE HUs DERIVADAS

Cuándo Generar HU Nueva:

Generar_HU_derivada_cuando:
  # Durante Análisis (A)
  - Se detecta bug estructural no relacionado al objetivo
  - Se identifica deuda técnica que bloquea
  - Se descubre dependencia no documentada

  # Durante Validación (V)
  - Hay trabajo detectado fuera del alcance original
  - Se requiere refactor previo no planificado
  - Se identifica mejora de UX no solicitada

  # Durante Ejecución (E)
  - Se encuentra código legacy que debe corregirse
  - Se descubre inconsistencia en otra parte del sistema
  - Se identifica oportunidad de optimización

Proceso de Generación:

1. DETECTAR: Identificar que algo está fuera del alcance
2. REGISTRAR: Documentar en la sección "HUs Derivadas" de la HU actual
3. CREAR: Generar archivo de HU con prefijo DERIVED-{HU-ORIGEN}-{N}
4. VINCULAR: Referenciar la HU origen en la nueva HU
5. PRIORIZAR: Marcar como pendiente para siguiente planificación
6. CONTINUAR: Seguir con la HU original sin desviarse

Template de Registro:

HUs_Derivadas:
  - id: "DERIVED-HU-001-001"
    origen: "HU-001"
    tipo: "bug | feature | refactor | deuda-tecnica"
    descripcion: "Descripción breve de lo detectado"
    detectado_en_fase: "A | V | E"
    prioridad_sugerida: "P0 | P1 | P2 | P3"
    notas: "Contexto adicional relevante"

---

CHECKLIST RÁPIDO CAPVED

Antes de Iniciar (C):

[ ] HU vinculada a proyecto/módulo/epic
[ ] Tipo clasificado (feature/fix/refactor/spike/doc-only)
[ ] Origen registrado (plan/descubrimiento/incidencia)
[ ] Documentos SIMCO relevantes identificados

Antes de Planificar (A completado):

[ ] Comportamiento de negocio entendido
[ ] Objetos impactados listados (todas las capas)
[ ] Dependencias identificadas
[ ] Riesgos documentados

Antes de Ejecutar (P+V completados):

[ ] Subtareas definidas por dominio
[ ] Orden de ejecución establecido
[ ] Criterios de aceptación definidos
[ ] Plan vs Análisis validado (todo cubierto)
[ ] Scope creep registrado (si existe)
[ ] HUs derivadas creadas (si aplica)

Durante Ejecución (E):

[ ] docs/ actualizado PRIMERO
[ ] Subtareas ejecutadas en orden
[ ] Build/lint pasa por subtarea
[ ] Progreso registrado

Antes de Cerrar (D):

[ ] Diagramas/modelos actualizados
[ ] Specs técnicas actualizadas
[ ] ADRs creados (si decisión arquitectónica)
[ ] Inventarios actualizados
[ ] Trazas actualizadas
[ ] HUs derivadas vinculadas
[ ] Lecciones aprendidas registradas

---

CONSECUENCIAS DE IGNORAR CAPVED

❌ Saltar Contexto (C)
   → HU sin trazabilidad, trabajo desconectado del plan

❌ Saltar Análisis (A)
   → Impacto no previsto, bugs en otras partes del sistema

❌ Saltar Planeación (P)
   → Ejecución caótica, trabajo rehecho, tiempo perdido

❌ Saltar Validación (V)
   → Scope creep no controlado, trabajo infinito

❌ Saltar Documentación (D)
   → Sistema diverge de docs/, confusión futura, onboarding difícil

---

LECCIONES APRENDIDAS

Registro Obligatorio:

Al cerrar cada HU, registrar:

Lecciones_Aprendidas:
  que_funciono_bien:
    - "Descripción de práctica exitosa"

  que_se_puede_mejorar:
    - "Descripción de área de mejora"

  para_futuras_HUs_similares:
    - "Recomendación específica para HUs del mismo tipo"

Ubicación:

• En el archivo de la HU (sección final)
• Consolidar mensualmente en orchestration/retrospectivas/

---

REFERENCIAS SIMCO

Fase CAPVED	SIMCO Relacionados
C - Contexto	SIMCO-INICIALIZACION.md, CONTEXTO-PROYECTO.md
A - Análisis	SIMCO-BUSCAR.md, TEMPLATE-ANALISIS.md
P - Planeación	TEMPLATE-PLAN.md, SIMCO-DELEGACION.md
V - Validación	TEMPLATE-VALIDACION.md
E - Ejecución	SIMCO-CREAR.md, SIMCO-MODIFICAR.md, SIMCO-DDL.md, etc.
D - Documentación	SIMCO-DOCUMENTAR.md, inventarios, trazas

---

ALIAS

@CAPVED:     core/orchestration/directivas/principios/PRINCIPIO-CAPVED.md
@TAREA:      core/orchestration/directivas/simco/SIMCO-TAREA.md
@TPL_CAPVED: core/orchestration/templates/TEMPLATE-TAREA-CAPVED.md

---

Este principio es OBLIGATORIO y NO puede ser ignorado por ningún agente.

---

Versión: 1.0.0 | Sistema: SIMCO + CAPVED | Tipo: Principio Fundamental