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