documentar arquitectura de Alpha y metricas PMI

docs/metricas_pmi.md

@@ -0,0 +1,331 @@
+# Alpha — Métricas de Desempeño en Proyectos
+
+> **Qué mido, cómo lo mido y por qué**. Justificación para reportes de avance a stakeholders.
+
+**Versión**: 1.0 | **Fecha**: 2026-05-26 | **Autor**: Ricardo Gonzalez (Teloprax)
+
+---
+
+## 1. Fundamentos
+
+Alpha mide el desempeño de proyectos y desarrolladores usando el marco **Earned Value Management (EVM)** del PMI, complementado con métricas ágiles (Scrum/Kanban). Toda unidad de trabajo se expresa en **Story Points (SP)**, donde **1 SP = 1 hora de trabajo efectivo**.
+
+### Fuentes de datos
+
+| Fuente | Dato | Frecuencia |
+|--------|------|------------|
+| KAPPA `/userstorys/` | HUs asignadas, estado, prioridad | On-demand |
+| KAPPA `/plannings/` | Fechas planeadas (inicio/fin) | On-demand |
+| KAPPA `/employees/` | Asignación usuario ↔ proyecto | On-demand |
+| Alpha Daily Log | Avance diario, horas, impedimentos | Diario |
+| Alpha Absences | Vacaciones, permisos, enfermedad | Eventual |
+| `calendar.ts` | Feriados Colombia (Ley Emiliani) | Automático |
+
+---
+
+## 2. Métricas de Proyecto (PMI-EVM)
+
+### 2.1 SPI — Schedule Performance Index
+
+> ¿Vamos al ritmo planeado?
+
+```
+SPI = EV / PV
+```
+
+| Variable | Definición | Cálculo |
+|----------|-----------|---------|
+| **EV** (Earned Value) | Valor del trabajo completado | SP completados × costo/hora |
+| **PV** (Planned Value) | Valor del trabajo planeado | SP planeados en el período × costo/hora |
+
+| SPI | Interpretación |
+|-----|---------------|
+| > 1.0 | Adelantado respecto al plan |
+| = 1.0 | Exactamente en plan |
+| < 1.0 | Atrasado respecto al plan |
+
+**Ejemplo**: Plan 40 SP en 2 semanas. Se completaron 32 SP.
+- PV = 40, EV = 32
+- SPI = 32/40 = **0.80** → 20% de atraso
+
+---
+
+### 2.2 CPI — Cost Performance Index
+
+> ¿Somos eficientes con las horas?
+
+```
+CPI = EV / AC
+```
+
+| Variable | Definición | Cálculo |
+|----------|-----------|---------|
+| **EV** (Earned Value) | Valor del trabajo completado | SP completados × costo/hora |
+| **AC** (Actual Cost) | Costo real incurrido | Horas reales registradas × costo/hora |
+
+| CPI | Interpretación |
+|-----|---------------|
+| > 1.0 | Por debajo del presupuesto (eficiente) |
+| = 1.0 | Exactamente en presupuesto |
+| < 1.0 | Por encima del presupuesto (ineficiente) |
+
+**Ejemplo**: 32 SP completados, pero se gastaron 38 horas reales.
+- EV = 32, AC = 38
+- CPI = 32/38 = **0.84** → 16% de sobrecosto en horas
+
+---
+
+### 2.3 SV — Schedule Variance
+
+```
+SV = EV - PV
+```
+
+Desviación en horas/dinero. **Positivo** = adelantado, **Negativo** = atrasado.
+
+---
+
+### 2.4 CV — Cost Variance
+
+```
+CV = EV - AC
+```
+
+Desviación en costo. **Positivo** = ahorro, **Negativo** = sobrecosto.
+
+---
+
+### 2.5 EAC — Estimate at Completion
+
+```
+EAC = BAC / CPI
+```
+
+| BAC | Budget at Completion | SP totales del proyecto |
+
+Proyección del costo total al final del proyecto basado en el CPI actual.
+
+---
+
+### 2.6 Días hábiles reales
+
+```
+días_hábiles = días_calendario_período
+             - fines_de_semana (sábado + domingo)
+             - feriados Colombia (Ley Emiliani, ver calendar.ts)
+             - ausencias del equipo (vacaciones, permisos, enfermedad)
+```
+
+Esto garantiza que las proyecciones de SPI y fechas de entrega sean realistas para el contexto colombiano.
+
+---
+
+## 3. Métricas Ágiles (por desarrollador)
+
+### 3.1 Velocity
+
+```
+velocity = Σ(SP completados) / período
+```
+
+| Período | Uso |
+|---------|-----|
+| Sprint (2 semanas) | Planificación de capacidad |
+| Semanal | Seguimiento táctico |
+| Diario | Micro-ajustes |
+
+**Interpretación**: Si un dev completa en promedio 16 SP/sprint, no se le deben asignar más de 16 SP en el siguiente sprint.
+
+---
+
+### 3.2 Burndown Chart
+
+```
+SP_restantes(día) = SP_totales - SP_completados(día)
+```
+
+Gráfico de SP restantes vs días hábiles. La línea ideal va del total a cero en la fecha de entrega. La línea real muestra si hay desviación.
+
+---
+
+### 3.3 Compliance (Cumplimiento)
+
+```
+compliance = HUs_completadas / HUs_asignadas
+```
+
+Porcentaje de historias de usuario entregadas vs comprometidas en el período.
+
+| Compliance | Calificación |
+|-----------|-------------|
+| ≥ 95% | Excelente |
+| 85-94% | Bueno |
+| 70-84% | Regular |
+| < 70% | Crítico |
+
+---
+
+### 3.4 Throughput
+
+```
+throughput = Work_Items_completados / período
+```
+
+Cantidad de ítems de trabajo terminados por unidad de tiempo. Útil para predecir capacidad futura (método Monte Carlo o percentiles).
+
+---
+
+### 3.5 Lead Time
+
+```
+lead_time = fecha_completada - fecha_asignada
+```
+
+Tiempo total desde que se asigna un HU hasta que se entrega. Incluye tiempo de espera + tiempo activo.
+
+---
+
+### 3.6 Cycle Time
+
+```
+cycle_time = fecha_completada - fecha_inicio_trabajo
+```
+
+Tiempo activo de trabajo (sin esperas). Idealmente < 3 días por HU.
+
+---
+
+## 4. Indicador Compuesto de Desempeño (CPI)
+
+```
+CPI_dev = (SPI × 0.25) + (CPI × 0.25) + (Compliance × 0.25) + (Velocity × 0.15) + (1 - Impedimentos/máx × 0.10)
+```
+
+| CPI_dev | Nivel |
+|---------|-------|
+| ≥ 0.90 | Alto desempeño |
+| 0.75 - 0.89 | Desempeño esperado |
+| 0.60 - 0.74 | Necesita atención |
+| < 0.60 | Crítico — intervención requerida |
+
+---
+
+## 5. Factores que afectan las métricas
+
+### 5.1 Feriados y días no laborables
+
+La función `isWorkingDay()` en `calendar.ts` excluye automáticamente:
+- Sábados y domingos
+- 18 feriados colombianos (incluyendo Ley Emiliani)
+
+### 5.2 Ausencias del equipo
+
+Las ausencias registradas (vacaciones, enfermedad, permisos) descuentan días hábiles del cálculo de capacidad, ajustando el PV (Planned Value) esperado.
+
+```
+PV_ajustado = PV × (días_hábiles_disponibles / días_hábiles_totales)
+```
+
+### 5.3 Impedimentos
+
+Cada impedimento registrado en el Daily Log afecta el indicador compuesto. Más de 3 impedimentos activos en una semana dispara una alerta.
+
+---
+
+## 6. Cálculo por proyecto
+
+### Paso a paso
+
+1. **Obtener línea base**: Fechas de inicio/fin del proyecto (de KAPPA plannings)
+2. **Calcular SP totales**: Sumar SP de todas las HUs del proyecto
+3. **Calcular días hábiles**: `workingDays(inicio, fin) - ausencias`
+4. **SP/día planeado**: `SP_totales / días_hábiles`
+5. **PV acumulado(día)**: `SP/día_planeado × día_del_proyecto`
+6. **EV acumulado(día)**: `Σ(SP de HUs completadas hasta el día)`
+7. **AC acumulado(día)**: `Σ(horas reales registradas)`
+8. **Calcular SPI, CPI, SV, CV** con las fórmulas anteriores
+
+### Ejemplo numérico
+
+| Dato | Valor |
+|------|-------|
+| Proyecto | 10 días hábiles (2 semanas) |
+| SP totales | 40 SP |
+| SP/día planeado | 4 SP/día |
+| Día 5 | PV = 20, EV = 16, AC = 18 horas |
+| SPI | 16/20 = 0.80 |
+| CPI | 16/18 = 0.89 |
+| EAC | 40/0.89 = 45 horas (5 horas extra proyectadas) |
+
+---
+
+## 7. Cálculo por desarrollador
+
+Mismas fórmulas, pero filtradas por `assigned_to = user_id`:
+
+```
+SPI_dev = EV_dev / PV_dev
+CPI_dev = EV_dev / AC_dev
+```
+
+Donde:
+- `EV_dev` = SP completados por el dev en el período
+- `PV_dev` = SP planeados para el dev (proporcional a su asignación)
+- `AC_dev` = Horas reales registradas por el dev
+
+---
+
+## 8. Visualización de reportes
+
+### Dashboard de proyecto
+
+| Widget | Métrica | Visualización |
+|--------|---------|--------------|
+| Semaforo SPI | SPI actual | 🟢 >1.0 🟡 0.8-1.0 🔴 <0.8 |
+| Semaforo CPI | CPI actual | 🟢 >1.0 🟡 0.8-1.0 🔴 <0.8 |
+| Burndown | SP restantes vs días | Gráfico de línea |
+| Velocity trend | Últimos 4 sprints | Gráfico de barras |
+| Top impediments | Impedimentos activos | Lista ordenada |
+
+### Dashboard de desarrollador
+
+| Widget | Métrica |
+|--------|---------|
+| CPI compuesto | Indicador numérico + semáforo |
+| HUs asignadas vs completadas | Barra de progreso |
+| Velocity semanal | Sparkline |
+| Lead time promedio | Número (días) |
+| Impedimentos activos | Contador |
+
+---
+
+## 9. Períodos de cálculo
+
+| Período | Actualización | Propósito |
+|---------|--------------|-----------|
+| Diario | Cada daily log guardado | Micro-seguimiento |
+| Semanal | Lunes 8:00 AM | Reporte de avance |
+| Sprint (2 sem) | Fin de sprint | Replanificación |
+| Proyecto | Bajo demanda | Reporte ejecutivo |
+
+---
+
+## 10. Referencias
+
+- **PMI PMBOK 7th Edition** — Earned Value Management (EVM)
+- **Scrum Guide 2020** — Velocity, Sprint Burndown
+- **Kanban Method** — Lead Time, Cycle Time, Throughput
+- **Ley Emiliani (Colombia)** — Traslado de feriados al lunes
+- **Algoritmo de Butcher** — Cálculo de Pascua (base para feriados variables)
+
+---
+
+## 11. Notas para stakeholders
+
+> Este documento respalda la metodología de medición usada en Alpha. Cualquier reporte generado por la herramienta se basa en estas fórmulas, alineadas con estándares internacionales de gestión de proyectos (PMI) y metodologías ágiles (Scrum/Kanban).
+
+**Alpha no reemplaza a un PM**. Es una herramienta de apoyo que:
+1. Centraliza datos de múltiples fuentes (KAPPA, daily logs, calendario)
+2. Calcula métricas objetivas automáticamente
+3. Genera reportes justificables con trazabilidad a los datos fuente
+4. Permite al BA/PM tomar decisiones informadas basadas en evidencia