# 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