---
name: evaluacion-agentes
description: >
  Framework de evaluación de agentes SWL con métricas pass@k y tracking de fiabilidad.
  Cargar cuando se necesite evaluar la efectividad de un agente, auditar su rendimiento
  histórico, diagnosticar agentes con baja fiabilidad o integrar métricas en swl:salud.
version: "1.0.0"
herramientasPermitidas: [Read, Grep]
exclusiones:
  - "No cargar para evaluar la calidad de un skill (SKILL.md) — ese es el trabajo de `autoresearch`; este skill mide agentes (frontmatter + instrucciones + historial de ejecución), no skills aislados."
  - "No cargar para evaluar si un artefacto del plan cumple criterios de aceptación — eso es `verificar-trabajo`; este skill genera métricas pass@k, no verifica slices."
  - "No cargar cuando se quiera hacer una revisión puntual de código producido por un agente — usar `revisor-codigo-swl` o `checklist-calidad`; este skill requiere historial de múltiples ejecuciones para ser significativo."
  - "No cargar si el agente tiene menos de 5 ejecuciones registradas — el cálculo de pass@k con n < 5 no es estadísticamente válido y llevaría a acciones incorrectas."
evolvable: true  # default para skill estandar
---
# Evaluación de Agentes SWL

Framework para medir, registrar y mejorar la fiabilidad de los agentes del sistema SWL
usando la métrica pass@k, estándar en benchmarks de modelos de lenguaje.

## Cuándo cargar

- Se evalúa la efectividad de un agente tras una sesión de trabajo
- Se audita el rendimiento histórico de agentes en `.planning/EVALUACION.md`
- Un agente produce resultados inesperados con frecuencia y se necesitan datos
- Se ejecuta `swl:salud` con la opción de incluir métricas de agentes
- Se decide si un agente necesita evolución mediante `swl:evolucionar`

---

## Métrica pass@k — Concepto

**pass@k** mide la probabilidad de que un agente produzca al menos una solución
correcta en k intentos sobre el mismo problema.

| Variante | Significado |
|----------|-------------|
| pass@1   | Éxito en el primer intento sin reintento |
| pass@3   | Éxito si se dan hasta 3 oportunidades |
| pass@5   | Éxito si se dan hasta 5 oportunidades |

**Interpretación práctica para SWL**:
- **pass@1 alto** → el agente produce output correcto en la primera ejecución.
  Indica instrucciones claras y bien calibradas.
- **pass@1 bajo pero pass@3 alto** → el agente necesita guidance pero puede
  autocorregirse. Candidato a mejora de instrucciones en su SKILL.md.
- **pass@3 bajo** → el agente falla sistemáticamente. Requiere evolución urgente.

---

## Fórmula de cálculo

La fórmula estadística exacta para estimar pass@k a partir de n ejecuciones con c correctas:

```
pass@k = 1 - ( C(n-c, k) / C(n, k) )

donde:
  n = número total de ejecuciones registradas
  c = número de ejecuciones con resultado correcto
  k = número de intentos evaluados (1, 3 o 5)
  C(a, b) = combinatorio "a sobre b" = a! / (b! * (a-b)!)
```

**Ejemplo concreto** — agente con 10 ejecuciones, 7 correctas, evaluando pass@1:

```
pass@1 = 1 - C(10-7, 1) / C(10, 1)
       = 1 - C(3, 1) / C(10, 1)
       = 1 - 3/10
       = 0.70  →  70%
```

**Cuando n < 5**: no calcular pass@k — la muestra es insuficiente para ser
representativa. Registrar como "datos insuficientes (n=N)".

---

## Criterios de éxito por ejecución

Una ejecución se registra como **correcta** si cumple TODOS los criterios aplicables:

| Criterio | Aplica a | Cómo verificar |
|----------|----------|----------------|
| Build pasa sin errores | Agentes implementadores | `npm run build` / `pytest` sin errores |
| Tests pasan | Agentes implementadores y QA | suite de tests verde |
| Review aprueba | Agentes revisores | revisor-codigo-swl da score >= 9.0 |
| Output tiene estructura esperada | Todos los agentes | frontmatter completo, secciones requeridas |
| Sin placeholders pendientes | Todos los agentes | grep -cE '\[(PENDIENTE|TBD)\]' output == 0 |
| Entregable referenciado en ESTADO.md | Agentes de documentación | ESTADO.md actualizado |

Si un criterio no aplica al tipo de agente, se omite de la evaluación.

---

## Objetivos por tipo de agente

| Tipo de agente | pass@1 objetivo | pass@3 objetivo | Acción si no se cumple |
|----------------|-----------------|-----------------|----------------------|
| Implementadores (backend, frontend) | >= 70% | >= 90% | Revisar instrucciones de implementación |
| Revisores (código, seguridad) | >= 85% | >= 95% | Revisar criterios de evaluación del agente |
| Build resolvers | >= 80% | >= 95% | Agregar ejemplos de errores frecuentes |
| Planificadores (planificador-swl) | >= 75% | >= 92% | Revisar formato de PLAN.md |
| Documentadores | >= 80% | >= 95% | Revisar templates en recursos/ |
| Orquestadores | >= 65% | >= 85% | Revisar lógica de delegación |

**Umbral de alerta**: pass@1 < 60% en cualquier tipo → el agente necesita mejora
urgente antes de la próxima sesión de producción.

---

## Formato de registro en EVALUACION.md

Cada evaluación se registra en `.planning/EVALUACION.md`. Si el archivo no existe,
crearlo al registrar la primera evaluación.

### Estructura del archivo

```markdown
# EVALUACION.md — Métricas de agentes SWL

Última actualización: YYYY-MM-DD

## Resumen ejecutivo

| Agente | Ejecuciones (n) | Correctas (c) | pass@1 | pass@3 | Estado |
|--------|-----------------|---------------|--------|--------|--------|
| planificador-swl | 12 | 9 | 75% | 92% | OK |
| backend-python-swl | 8 | 5 | 63% | 88% | REVISAR |
| revisor-codigo-swl | 15 | 13 | 87% | 100% | OK |

## Detalle por agente

### planificador-swl

- **n total**: 12 ejecuciones
- **c correctas**: 9
- **pass@1**: 75%  (objetivo: >= 75%) — CUMPLE
- **pass@3**: 92%  (objetivo: >= 92%) — CUMPLE
- **Errores frecuentes**: slices sin criterio de éxito definido (2 casos)
- **Última evaluación**: 2026-03-25

#### Historial reciente (últimas 5)

| Fecha | Resultado | Notas |
|-------|-----------|-------|
| 2026-03-25 | correcto | — |
| 2026-03-20 | incorrecto | faltó slice de migración |
| 2026-03-15 | correcto | — |
| 2026-03-10 | correcto | — |
| 2026-03-05 | correcto | — |
```

### Reglas de registro

- Registrar cada ejecución al finalizar la sesión, no acumular varias sin registrar.
- El campo "Notas" debe explicar el motivo del fallo si el resultado fue incorrecto.
  Un registro sin notas en fallo es inútil para mejorar el agente.
- Recalcular pass@1 y pass@3 cada vez que se agrega un registro nuevo.
- Si n aumenta pero c no (fallo), actualizar los porcentajes.

---

## Proceso de evaluación — paso a paso

1. **Identificar el agente evaluado** y localizar su entrada en EVALUACION.md.
   Si no existe, crear la sección con n=0, c=0.

2. **Determinar si la ejecución fue correcta** aplicando los criterios de la tabla
   de criterios de éxito. Documentar cuáles criterios se verificaron.

3. **Registrar en el historial** con fecha, resultado y notas si hubo fallo.

4. **Incrementar n**. Si fue correcto, incrementar también c.

5. **Recalcular pass@1 y pass@3** usando la fórmula. Si n < 5, registrar
   "datos insuficientes" en lugar del porcentaje.

6. **Comparar contra objetivo** de la tabla de objetivos por tipo.
   Si pass@1 < 60%, anotar "ALERTA" en el campo Estado.

7. **Si Estado = ALERTA o REVISAR**, abrir un issue o nota en ESTADO.md para
   que `swl:evolucionar` lo procese en la siguiente sesión.

---

## Integración con swl:salud

El comando `swl:salud` puede incluir un resumen de métricas de agentes como
Paso 6b del diagnóstico. El formato esperado en SALUD.md es:

```markdown
## Métricas de agentes (pass@1)

| Agente | pass@1 | pass@3 | Estado |
|--------|--------|--------|--------|
| planificador-swl | 75% | 92% | OK |
| backend-python-swl | 63% | 88% | REVISAR |

Agentes en alerta (pass@1 < 60%): ninguno
Agentes con datos insuficientes (n < 5): 3
```

Si `.planning/EVALUACION.md` no existe, `swl:salud` reporta:
"Métricas de agentes: sin datos — ejecutar evaluacion-agentes para iniciar tracking."

---

## Cuándo un agente necesita mejora

Un agente necesita mejora cuando ocurre cualquiera de estas condiciones:

- **pass@1 < 60%** sostenido durante 5 o más ejecuciones consecutivas
- **El mismo tipo de fallo** aparece en 3 o más registros del historial
- **pass@3 < 80%** en cualquier tipo de agente
- Un fallo causó un incidente en producción (independiente del porcentaje)

**Acción**: Invocar `swl:evolucionar` con el nombre del agente y los errores
frecuentes del historial como contexto. El agente de evolución revisará las
instrucciones y propondrá cambios específicos.

---

## Evaluación conductual de skills — patrón de 3 brazos

pass@k mide la fiabilidad de agentes. Pero ¿cómo medir si un **skill** realmente
cambia el comportamiento del modelo, o si el mismo resultado se obtendría con
cualquier instrucción genérica?

### El problema de la conflación

Si se compara "modelo con skill" vs "modelo sin nada", toda mejora se atribuye
al skill — incluso si una instrucción mínima como "sé conciso" lograría lo mismo.
Esto infla el valor percibido de skills que solo repiten conocimiento general.

### Harness de evaluación de 3 brazos

| Brazo | System prompt | Propósito |
|-------|--------------|-----------|
| **baseline** | Ninguno | Medir capacidad base del modelo |
| **control** | Instrucción genérica del dominio (ej: "Escribe código Python limpio y testeado") | Medir el efecto de cualquier instrucción mínima |
| **tratamiento** | Instrucción genérica + contenido del skill | Medir el delta real del skill |

**La métrica que importa**: tratamiento vs control (no tratamiento vs baseline).
Si el skill no mejora sobre el control genérico, su contenido no aporta valor
diferencial — el modelo ya sabía hacerlo con una instrucción mínima.

### Cómo aplicar

1. Definir 5-10 prompts representativos del dominio del skill
2. Ejecutar cada prompt en los 3 brazos (misma temperatura, mismo modelo)
3. Evaluar las respuestas con criterios binarios (correcto/incorrecto) o escala
4. Comparar: ¿el brazo tratamiento supera consistentemente al control?

**Cuándo usar**: Al decidir si un skill candidato justifica su incorporación al
sistema, o al auditar si un skill existente aporta valor real. No es necesario
para cada evaluación rutinaria — es una técnica de diagnóstico profundo.

**Resultado esperado**: Si tratamiento > control en >= 60% de los prompts,
el skill aporta valor. Si no, su contenido es redundante con el conocimiento
base del modelo y debe reescribirse con foco en gotchas y decisiones no obvias.

---

## Taxonomía de brechas — por qué fallan los agentes

Cuando un agente falla (pass@1 = incorrecto), la causa raíz no siempre es "el agente
está mal". Clasificar el tipo de brecha antes de proponer correcciones evita aplicar
la solución incorrecta (ej. reescribir un skill cuando el problema era falta de herramienta).

| Tipo de brecha | Síntoma típico | Acción correctiva |
|----------------|---------------|-------------------|
| **Skill faltante** | El agente improvisa donde debería seguir un patrón establecido | Crear o enriquecer el skill del dominio |
| **Herramienta faltante** | El agente describe lo que haría pero no puede ejecutarlo | Agregar MCP tool, script en `scripts/` o acceso a herramienta |
| **Permiso faltante** | El agente intenta una acción y recibe denegación | Ajustar permisos en `allowedTools` o configuración de sandbox |
| **Memoria faltante** | El agente re-pregunta decisiones ya tomadas en sesiones anteriores | Persistir en ESTADO.md, DECISIONS.md o memory del sistema |
| **Mala descomposición** | El agente produce un resultado parcial o mezcla responsabilidades | Revisar la delegación en el orquestador o el PLAN.md |
| **Verificación insuficiente** | El agente entrega resultado incorrecto pero confiado | Agregar criterios de éxito explícitos o harness de validación |
| **Autonomía insegura** | El agente toma decisiones irreversibles sin confirmación | Agregar checkpoint humano o reducir `nivelRiesgo` |
| **Modelo inadecuado** | El agente produce output superficial para la complejidad de la tarea | Escalar tier del modelo (haiku→sonnet→opus) según tabla Model-Tier |
| **Sobrecarga de contexto** | El agente olvida instrucciones tempranas o se contradice | Compactar contexto, usar `/swl:compactar`, reducir archivos cargados |

**Proceso**: Al registrar un fallo en el historial de EVALUACION.md, anotar el tipo
de brecha en la columna "Notas". Cuando un tipo acumula 3+ ocurrencias, la acción
correctiva correspondiente se convierte en prioridad para `/swl:evolucionar`.

---

## Anti-patrones en evaluación

- **Registrar sin verificar**: marcar como correcto sin correr los criterios
  de éxito. Contamina las métricas y oculta problemas reales.
- **No registrar fallos**: solo registrar éxitos infla artificialmente pass@1.
  Todos los intentos se registran, independiente del resultado.
- **Evaluar con n < 5**: un porcentaje con 3 ejecuciones no es estadísticamente
  representativo. Reportar como "datos insuficientes".
- **Comparar entre tipos**: un revisor con pass@1 = 80% y un implementador con
  pass@1 = 80% no son equivalentes. Los objetivos por tipo existen por una razón.
- **Atribuir mejoras sin grupo control**: medir skill vs baseline conflaciona el
  efecto del skill con el efecto de dar cualquier instrucción. Usar 3 brazos.

## Cuándo NO cargar

- Se quiere mejorar un SKILL.md específico — eso es `autoresearch`, que trabaja sobre el texto del skill, no sobre métricas de ejecución de agente.
- Se quiere verificar si un artefacto del plan cumple criterios de aceptación — eso es `verificar-trabajo`; este skill opera sobre historial de múltiples corridas, no sobre un entregable puntual.
- El agente en cuestión tiene menos de 5 ejecuciones registradas en EVALUACION.md — el pass@k sin datos suficientes produce porcentajes que llevan a acciones incorrectas.
- Se hace revisión puntual de la calidad del código de un agente — cargar `checklist-calidad` o invocar `revisor-codigo-swl`; este skill no evalúa artefactos individuales.

## Gotchas / Errores comunes no obvios

- **pass@3 calculado como promedio de 3 corridas en lugar de con la fórmula binomial**: el resultado aparece como 67% cuando la fórmula correcta `1 - C(n-c, k)/C(n, k)` daría 92%. Causa: usar `c/n` directamente en lugar de aplicar la fórmula pass@k estándar. Solución: usar siempre `pass@k = 1 - C(n-c, k) / C(n, k)`; para los valores típicos (n=12, k=3), la diferencia entre la fórmula correcta y el promedio simple es mayor al 20%.
- **Brecha de tipo "skill faltante" tratada como "modelo inadecuado"**: el equipo escala a Opus porque el agente improvisa, cuando el problema real es que no existe un skill para ese dominio. Causa: no diagnosticar el tipo de brecha antes de actuar. Solución: antes de escalar modelo, verificar en la taxonomía de brechas si el agente tiene acceso a un skill del dominio — si no existe, crearlo es más efectivo y económico que escalar de Sonnet a Opus.
- **Evaluación con los mismos 3 prompts en cada sesión**: el pass@1 llega al 100% pero el agente falla en producción con prompts diferentes. Causa: el conjunto de evaluación no es representativo del uso real. Solución: rotar el conjunto de prompts cada 30 días usando casos de uso reales capturados en `.planning/sessions/`; un conjunto estático que siempre pasa deja de ser informativo.
- **Sesión del harness de 3 brazos comparando baseline vs tratamiento (sin control)**: la mejora del skill se atribuye al contenido del skill cuando parte de la mejora viene de tener cualquier instrucción. Causa: omitir el brazo "control" (instrucción genérica) del harness. Solución: el brazo control es obligatorio — sin él no se puede saber si el contenido del skill supera una instrucción mínima de una línea.
