# PLAN DE VALIDACION DOCUMENTAL - MICHANGARRITO

**ID:** MCH-DOC-VAL-2026-01-17
**Tipo:** Validacion y Mejora Documental
**Fecha:** 2026-01-17
**Autor:** Agente Orquestador
**Estado:** En Revision
**Ciclo:** CAPVED

---

## 1. RESUMEN EJECUTIVO

### Analisis Realizado
Se realizo un analisis exhaustivo de la documentacion del proyecto michangarrito, cubriendo:
- 35 epicas (MCH-001 a MCH-035)
- 4 catalogos de definiciones
- 5 inventarios de orquestacion
- 14 integraciones externas
- 11 ADRs

### Estado Global

| Area | Calificacion | Estado |
|------|--------------|--------|
| Estructura de Epicas | 70% | Requiere estandarizacion |
| Definiciones Tecnicas | 40% | Gaps criticos |
| Inventarios | 75% | Inconsistencias de conteos |
| Integraciones | 88% | Excelente |
| ADRs | 90% | Excelente |
| Trazabilidad | 50% | Incompleta |

### Conclusion
**Estado: PARCIALMENTE VALIDO - REQUIERE CORRECCIONES**

---

## 2. GAPS IDENTIFICADOS (PRIORIZADOS)

### P0 - CRITICOS (Bloquean implementacion)

| ID | Gap | Area | Descripcion | Impacto |
|----|-----|------|-------------|---------|
| GAP-001 | HU sin formato estandar | Epicas | MCH-001 a MCH-027 no tienen HU formales (MCH-US-XXX) ni Story Points | Planificacion imposible |
| GAP-002 | Metodos de services no documentados | Definiciones | SERVICES-CATALOG.md no especifica metodos, parametros ni retornos | Backend devs sin referencia |
| GAP-003 | Conteo de tablas inconsistente | Inventarios | MASTER: 53 vs DATABASE: 47 tablas | Incertidumbre de alcance |
| GAP-004 | Propiedades de entities no documentadas | Definiciones | ENTITIES-CATALOG.md no lista campos de cada entity | Backend devs sin referencia |

### P1 - ALTOS (Impactan integridad)

| ID | Gap | Area | Descripcion | Impacto |
|----|-----|------|-------------|---------|
| GAP-005 | DATABASE-SCHEMA incompleto | Definiciones | Solo 4 de 47 tablas detalladas con columnas | DDL manual |
| GAP-006 | Trazas desactualizadas | Trazabilidad | TRAZA-BACKEND 2026-01-07, TRAZA-FRONTEND incompleta | Estado desconocido |
| GAP-007 | Herencia framework conflictiva | Integracion WS | _inheritance.yml dice Express, inventarios dicen NestJS | Confusion arquitectural |
| GAP-008 | Controllers no documentados | Definiciones | 20 controllers sin documentacion (65 DTOs tampoco) | Frontend devs sin referencia |

### P2 - MEDIOS (Impactan mantenibilidad)

| ID | Gap | Area | Descripcion | Impacto |
|----|-----|------|-------------|---------|
| GAP-009 | Falta EPICTRACES.yml | Trazabilidad | No existe mapeo Epica → Tarea → Objeto | Rastreo imposible |
| GAP-010 | Carpeta tareas/ no existe | Gobernanza | Obligatoria por CLAUDE.md Regla 7 | Gobernanza incompleta |
| GAP-011 | Story Points faltantes | Epicas | MCH-001 a MCH-027 sin SP | Estimacion imposible |
| GAP-012 | Estado de entregables inconsistente | Epicas | Algunos con estado, otros sin | Tracking incompleto |

### P3 - BAJOS (Mejoras deseables)

| ID | Gap | Area | Descripcion |
|----|-----|------|-------------|
| GAP-013 | Integraciones mock sin clarificar | Integraciones | INT-005, INT-006 estado ambiguo |
| GAP-014 | Metricas de exito faltantes | Epicas | Solo MCH-006, MCH-029 las tienen |
| GAP-015 | ADRs no vinculados a epicas | Trazabilidad | Epicas tempranas sin ref a ADRs |

---

## 3. PLAN DE TAREAS

### Estructura de Ejecucion

```
VALIDACION-DOCUMENTAL-MCH
│
├── TAREA-001: Estandarizar Epicas (P0)
│   ├── 001-A: Agregar HU formales a MCH-001 a MCH-027
│   ├── 001-B: Agregar Story Points a todas las epicas
│   └── 001-C: Estandarizar estado de entregables
│
├── TAREA-002: Completar Definiciones (P0)
│   ├── 002-A: Documentar metodos de services
│   ├── 002-B: Documentar propiedades de entities
│   ├── 002-C: Completar DATABASE-SCHEMA
│   └── 002-D: Documentar Controllers y DTOs
│
├── TAREA-003: Sincronizar Inventarios (P1)
│   ├── 003-A: Auditoria de tablas reales vs documentadas
│   ├── 003-B: Sincronizar conteos en todos los inventarios
│   └── 003-C: Corregir herencia framework
│
├── TAREA-004: Completar Trazabilidad (P1)
│   ├── 004-A: Actualizar TRAZA-TAREAS-BACKEND
│   ├── 004-B: Completar TRAZA-TAREAS-FRONTEND
│   ├── 004-C: Crear EPICTRACES.yml
│   └── 004-D: Crear estructura tareas/
│
├── TAREA-005: Mejorar Integraciones (P2)
│   ├── 005-A: Completar INT-004 (MercadoPago)
│   └── 005-B: Clarificar estado de INT-005, INT-006
│
└── TAREA-006: Integracion Workspace (P2)
    ├── 006-A: Actualizar trazabilidad bidireccional
    └── 006-B: Registrar en TRACEABILITY-MASTER del workspace
```

---

## 4. DETALLE DE TAREAS

### TAREA-001: Estandarizar Epicas

**Objetivo:** Normalizar todas las epicas al formato MCH-029/MCH-032

**Subtareas:**

| ID | Subtarea | Archivos | Estimacion |
|----|----------|----------|------------|
| 001-A | Agregar HU formales (MCH-US-XXX) | 27 epicas (MCH-001 a MCH-027) | Alto |
| 001-B | Agregar Story Points totales | 27 epicas | Medio |
| 001-C | Estandarizar estado entregables | 35 epicas | Bajo |

**Criterios de Aceptacion:**
- [ ] Todas las epicas tienen seccion "Historias de Usuario" con formato MCH-US-XXX
- [ ] Todas las HU tienen: AS/WANT/FOR, Story Points, Criterios de Aceptacion
- [ ] Todas las epicas tienen Story Points totales en frontmatter
- [ ] Todos los entregables tienen estado (Completado/En Progreso/Pendiente)

**Dependencias:** Ninguna (puede ejecutarse en paralelo)

---

### TAREA-002: Completar Definiciones

**Objetivo:** Documentar especificaciones tecnicas para implementadores

**Subtareas:**

| ID | Subtarea | Archivos | Estimacion |
|----|----------|----------|------------|
| 002-A | Documentar metodos de services | SERVICES-CATALOG.md | Alto |
| 002-B | Documentar propiedades de entities | ENTITIES-CATALOG.md | Alto |
| 002-C | Completar tablas en DATABASE-SCHEMA | DATABASE-SCHEMA.md | Alto |
| 002-D | Crear CONTROLLERS-CATALOG.md, DTOS-CATALOG.md | Nuevos archivos | Alto |

**Criterios de Aceptacion:**
- [ ] Cada service tiene lista de metodos con parametros y retornos
- [ ] Cada entity tiene lista de propiedades con tipos
- [ ] DATABASE-SCHEMA tiene todas las 47+ tablas con columnas
- [ ] Controllers documentados con endpoints
- [ ] DTOs documentados con validaciones

**Dependencias:**
- 002-C depende de TAREA-003-A (auditoria de tablas)

---

### TAREA-003: Sincronizar Inventarios

**Objetivo:** Resolver inconsistencias de conteos entre inventarios

**Subtareas:**

| ID | Subtarea | Archivos | Estimacion |
|----|----------|----------|------------|
| 003-A | Auditoria de tablas reales | Scripts SQL, inventarios | Medio |
| 003-B | Sincronizar conteos | 5 inventarios | Medio |
| 003-C | Corregir herencia framework | _inheritance.yml | Bajo |

**Criterios de Aceptacion:**
- [ ] Conteo de tablas coincide en MASTER y DATABASE inventarios
- [ ] Conteo de entities coincide en MASTER y BACKEND inventarios
- [ ] _inheritance.yml refleja NestJS (no Express)
- [ ] Fechas de actualizacion sincronizadas

**Dependencias:** Ninguna

---

### TAREA-004: Completar Trazabilidad

**Objetivo:** Establecer trazabilidad completa Epica → Tarea → Objeto

**Subtareas:**

| ID | Subtarea | Archivos | Estimacion |
|----|----------|----------|------------|
| 004-A | Actualizar TRAZA-BACKEND | TRAZA-TAREAS-BACKEND.md | Medio |
| 004-B | Completar TRAZA-FRONTEND | TRAZA-TAREAS-FRONTEND.md | Medio |
| 004-C | Crear EPICTRACES.yml | Nuevo archivo | Alto |
| 004-D | Crear estructura tareas/ | orchestration/tareas/ | Bajo |

**Criterios de Aceptacion:**
- [ ] Trazas actualizadas a fecha actual
- [ ] Estados consistentes con inventarios
- [ ] EPICTRACES.yml mapea cada MCH-XXX a sus tareas y objetos
- [ ] Carpeta tareas/ existe con estructura SIMCO

**Dependencias:**
- 004-C depende de TAREA-001 (para tener HU definidas)

---

### TAREA-005: Mejorar Integraciones

**Objetivo:** Completar documentacion de integraciones pendientes

**Subtareas:**

| ID | Subtarea | Archivos | Estimacion |
|----|----------|----------|------------|
| 005-A | Completar INT-004 | INT-004-mercadopago.md | Medio |
| 005-B | Clarificar INT-005, INT-006 | INT-005-clip.md, INT-006-codi-banxico.md | Bajo |

**Criterios de Aceptacion:**
- [ ] INT-004 tiene checklist de implementacion completo
- [ ] INT-004 tiene ejemplos de flujo de pago
- [ ] INT-005, INT-006 tienen estado clarificado (Mock/Future/Deprecated)

**Dependencias:** Ninguna

---

### TAREA-006: Integracion Workspace

**Objetivo:** Establecer trazabilidad con workspace padre

**Subtareas:**

| ID | Subtarea | Archivos | Estimacion |
|----|----------|----------|------------|
| 006-A | Actualizar trazabilidad bidireccional | WS-REFERENCES.yml | Bajo |
| 006-B | Registrar en TRACEABILITY-MASTER | orchestration/TRACEABILITY-MASTER.yml (workspace) | Bajo |

**Criterios de Aceptacion:**
- [ ] Workspace tiene entrada para michangarrito en TRACEABILITY-MASTER
- [ ] Michangarrito referencia correctamente directivas del workspace

**Dependencias:**
- Depende de TAREA-003 (inventarios sincronizados)

---

## 5. ORDEN DE EJECUCION RECOMENDADO

```
     PARALELO                           SECUENCIAL
     ────────                           ──────────

┌─────────────────────────┐    ┌─────────────────────────┐
│ TAREA-003: Inventarios  │───►│ TAREA-002-C: DB Schema  │
│ (Auditoria primero)     │    │ (Requiere conteo real)  │
└─────────────────────────┘    └─────────────────────────┘
                                          │
┌─────────────────────────┐               ▼
│ TAREA-001: Epicas       │    ┌─────────────────────────┐
│ (Estandarizacion)       │───►│ TAREA-004-C: EPICTRACES │
└─────────────────────────┘    │ (Requiere HU definidas) │
                               └─────────────────────────┘
┌─────────────────────────┐               │
│ TAREA-002-A,B,D:        │               ▼
│ Services, Entities      │    ┌─────────────────────────┐
│ Controllers, DTOs       │    │ TAREA-006: Workspace    │
└─────────────────────────┘    │ (Al final)              │
                               └─────────────────────────┘
┌─────────────────────────┐
│ TAREA-005: Integraciones│
│ (Independiente)         │
└─────────────────────────┘
```

### Fases Recomendadas

**Fase 1 (Paralelo):** TAREA-001, TAREA-003, TAREA-005
**Fase 2 (Secuencial):** TAREA-002-C (tras 003), TAREA-004-C (tras 001)
**Fase 3 (Paralelo):** TAREA-002-A,B,D, TAREA-004-A,B,D
**Fase 4 (Final):** TAREA-006

---

## 6. PERFILES DE AGENTES RECOMENDADOS

| Tarea | Perfil | Alias |
|-------|--------|-------|
| TAREA-001 | Requirements Analyst | @PERFIL_REQUIREMENTS |
| TAREA-002-A,B,D | Backend Developer | @PERFIL_BACKEND |
| TAREA-002-C | Database Specialist | @PERFIL_DATABASE |
| TAREA-003 | Architecture Analyst | @PERFIL_ARCHITECT |
| TAREA-004 | Documentation | @PERFIL_DOCS |
| TAREA-005 | Backend Developer | @PERFIL_BACKEND |
| TAREA-006 | KB Manager | @PERFIL_KB_MANAGER |

---

## 7. METRICAS DE EXITO

### Al Completar Todas las Tareas

| Metrica | Antes | Despues |
|---------|-------|---------|
| Epicas con HU formales | 8/35 (23%) | 35/35 (100%) |
| Epicas con Story Points | 8/35 (23%) | 35/35 (100%) |
| Entities documentadas | 25/37 (68%) | 37/37 (100%) |
| Services con metodos | 0/22 (0%) | 22/22 (100%) |
| Tablas en DB-SCHEMA | 4/47 (9%) | 47/47 (100%) |
| Inventarios coherentes | 75% | 100% |
| Trazas actualizadas | 50% | 100% |
| Integracion Workspace | 80% | 100% |

---

## 8. REFERENCIAS

- [CLAUDE.md](../../../../CLAUDE.md) - Reglas de gobernanza
- [PRINCIPIO-CAPVED.md](../../../../orchestration/directivas/principios/PRINCIPIO-CAPVED.md) - Ciclo de vida
- [_MAP.md](../../docs/_MAP.md) - Mapa de documentacion
- [MAPA-DOCUMENTACION.yml](../MAPA-DOCUMENTACION.yml) - Mapa de orquestacion

---

**Estado:** EN PROGRESO
**Siguiente Paso:** Continuar con tareas pendientes

---

## 9. REGISTRO DE EJECUCION

### Tareas Completadas

| Tarea | Subtarea | Estado | Archivos Modificados |
|-------|----------|--------|----------------------|
| TAREA-003 | 003-A: Auditoria tablas | Completado | - |
| TAREA-003 | 003-B: Sincronizar conteos | Completado | MASTER_INVENTORY.yml |
| TAREA-003 | 003-C: Corregir herencia | Completado | _inheritance.yml |
| TAREA-001 | MCH-001 estandarizada | Completado | MCH-001-infraestructura-base.md |

### Cambios Aplicados

1. **MASTER_INVENTORY.yml:**
   - Corregido conteo tablas: 53 → 47
   - Corregido conteo controllers: 25 → 20
   - Corregido conteo entities: 42 → 37

2. **_inheritance.yml:**
   - Corregido stack: Express → NestJS 10.3.0
   - Corregido frontend: React 18 → React 19.2.0
   - Corregidos schemas BD: pos_* → public, auth, catalog, etc.
   - Corregidos modulos propios con IDs MCH-XXX correctos
   - Agregados modulos SaaS integrados

3. **MCH-001-infraestructura-base.md:**
   - Agregado story_points: 8 al frontmatter
   - Actualizado simco_version: 3.8.0 → 4.0.1
   - Agregadas 3 HU formales con formato MCH-US-XXX
   - Agregados criterios de aceptacion con formato [CA-XXX-N]
   - Agregadas tareas con formato MCH-TT-XXX-NN
   - Agregado resumen de Story Points

### Tareas Pendientes

| Tarea | Subtareas | Archivos Pendientes |
|-------|-----------|---------------------|
| TAREA-001 | 26 epicas mas | MCH-002 a MCH-028 |
| TAREA-002 | A,B,C,D | SERVICES, ENTITIES, DATABASE-SCHEMA, CONTROLLERS |
| TAREA-004 | A,B,C,D | Trazas, EPICTRACES.yml, tareas/ |
| TAREA-005 | A,B | INT-004, INT-005, INT-006 |
| TAREA-006 | A,B | Workspace TRACEABILITY-MASTER |

### Fecha Registro
- **Fecha:** 2026-01-17
- **Agente:** Orquestador - Validacion Documental