---
name: autoresearch
description: >
  Protocolo de auto-mejora iterativa de skills basado en Autoresearch (Karpathy).
  Define cómo crear checklists de evaluación por skill (3-6 items binarios ponderados),
  ejecutar el loop de mutación atómica (cambiar una cosa → evaluar → keep/revert),
  y mejorar skills hasta 95%+ de score. Cargar cuando se quiera mejorar la calidad
  de un skill o agente existente de forma medible y automatizada, o cuando
  auto-evolucion-swl necesite una metodología de mejora iterativa con scoring.
version: "1.0.0"
herramientasPermitidas: [Read, Bash]
exclusiones:
  - "No cargar para mejorar el output de una sola sesión; el loop de autoresearch opera sobre el SKILL.md del skill, no sobre outputs puntuales."
  - "No cargar si el skill tiene score baseline < 60% sin diagnóstico previo — un skill deficiente a ese nivel probablemente necesita reescritura antes de iteración incremental."
  - "No cargar para evaluar agentes; la metodología aplica a skills (SKILL.md), no a agentes (frontmatter de agente). Para agentes usar `evaluacion-agentes`."
  - "No cargar si el checklist no está redactado con criterios binarios verificables — iterar sobre un checklist subjetivo produce mutaciones sin dirección."
evolvable: true  # default para skill estandar
---
# Autoresearch — Loop de Auto-Mejora Iterativa de Skills

Protocolo que convierte la mejora de skills de un proceso manual a uno **automatizado
y medible**. El humano define qué es "bueno" (checklist); la máquina descubre cómo
lograrlo (loop de mutación). Basado en el método Autoresearch de Andrej Karpathy,
adaptado para Claude Agent Skills.

**Principio**: Si puedes evaluarlo con un score, puedes autoresearch-arlo.

## Cuándo cargar este skill

Invoca `Skill("autoresearch")` cuando:

- Se quiere mejorar un skill existente de forma medible
- Un skill produce outputs que consistentemente no cumplen expectativas
- `auto-evolucion-swl` identifica un candidato para mejora iterativa
- Se necesita un proceso reproducible de mejora antes de una release
- Se quiere optimizar cualquier prompt que se use repetidamente

## El Loop — Resumen visual

```
[1] Crear checklist (3-6 items) → [2] Baseline score
                                        ↓
                              ┌─── [3] El loop ◄──────────┐
                              │         ↓                  │
                              │  Cambiar UNA cosa          │
                              │         ↓                  │
                              │  Evaluar vs checklist      │
                              │         ↓                  │
                              │  ¿Mejoró? ─── Sí → KEEP ──┘
                              │     │
                              │     No → REVERT ───────────┘
                              │
                              └─── Sale cuando: 95%+ × 3 consecutivas
                                        ↓
                              [4] Skill mejorado + changelog
```

## Paso 1 — Crear el checklist de evaluación

El checklist es lo ÚNICO que el humano define. Requisitos por item:

- **Binario**: sí/no — sin subjetividad
- **Observable**: verificable leyendo el output
- **Independiente**: un item no depende de otro
- **Ponderado**: peso 1-5 según impacto

```markdown
## Checklist — [nombre-skill]

| # | Criterio | Peso | Verificación |
|---|----------|------|-------------|
| 1 | [criterio concreto y verificable] | [1-5] | [cómo verificar] |
| 2 | [criterio concreto y verificable] | [1-5] | [cómo verificar] |
| 3 | [criterio concreto y verificable] | [1-5] | [cómo verificar] |
```

Ver [recursos/checklist-template.md](recursos/checklist-template.md) para ejemplos
por dominio (backend, frontend, testing, docs, agentes).

## Paso 2 — Obtener baseline score

Ejecutar el skill con un **caso de prueba representativo** y evaluar:

```
score = Σ(items_cumplidos × peso) / Σ(todos_pesos) × 100
```

Usar el script de scoring para cálculo determinista:

```bash
node scripts/calcular-score.js '{"items":[{"peso":5,"cumple":true},{"peso":3,"cumple":false}]}'
```

**Formato de reporte baseline:**

```markdown
## Baseline — [nombre-skill] — [fecha]
Caso de prueba: [descripción]
Score: [N]%

| # | Criterio | Peso | ✓/✗ | Notas |
|---|----------|------|-----|-------|
| 1 | [criterio] | [N] | ✓/✗ | [observación] |
```

## Paso 3 — El loop de mutación

Corre hasta alcanzar **95%+ en 3 evaluaciones consecutivas** o **máximo 10 rounds**:

```python
consecutive_passes = 0
round = 0

while consecutive_passes < 3 and round < MAX_ROUNDS:
    round += 1
    item = seleccionar_item_mayor_impacto(checklist)
    mutacion = proponer_mutacion_atomica(skill, item)
    aplicar(mutacion)
    new_score = evaluar(skill, caso_prueba, checklist)

    if new_score >= old_score:
        old_score = new_score
        registrar_changelog("KEEP", mutacion, old_score, new_score)
    else:
        revertir(mutacion)
        registrar_changelog("REVERT", mutacion, old_score, new_score)

    consecutive_passes = consecutive_passes + 1 if new_score >= 95 else 0
```

### Tipos de mutación (uno a la vez, SIEMPRE)

| Tipo | Riesgo | Ejemplo |
|------|--------|---------|
| Agregar regla | Bajo | `+ SIEMPRE usar selectinload` |
| Agregar ejemplo MAL/BIEN | Bajo | `+ bloque de código correcto vs incorrecto` |
| Agregar lista negra | Bajo | `+ PROHIBIDO: @validator, lazy loading` |
| Refinar regla existente | Medio | `validar → validar con model_validator v2` |
| Reordenar secciones | Medio | `mover regla crítica al inicio` |
| Eliminar ruido | Alto | `- texto que no impacta el score` |

**Regla crítica**: UNA mutación por iteración. Si cambias varias cosas, no sabrás
cuál causó la mejora o el deterioro.

### Selección de mutación — Priorización

```
prioridad = peso_item × (1 si no_cumple else 0) × factor_tipo

factor_tipo:
  1.0 = agregar regla/ejemplo (no modifica existente)
  0.8 = refinar (modifica pero acota)
  0.6 = reordenar (puede afectar flujo)
  0.4 = eliminar (riesgo de perder información)
```

Siempre atacar primero: **peso alto + no cumple + tipo bajo riesgo**.

## Paso 4 — Registro por iteración

```markdown
## Round [N] — [fecha]
Score: [X]% → [Y]% ([+/-Z]%)
Mutación: [tipo] — [descripción concreta]
Item target: #[N] ([criterio])
Resultado: KEEP | REVERT
Razón: [por qué mejoró o empeoró]
```

## Paso 5 — Finalización

Al alcanzar 95%+ × 3 consecutivas (o max rounds):

1. **Guardar** la versión final del skill
2. **Versionar**: MINOR si cambios significativos, PATCH si ajustes menores
3. **Generar reporte final**:

```markdown
## Reporte Autoresearch — [nombre-skill]
Fecha: [fecha]
Rounds ejecutados: [N]
Score: [baseline]% → [final]%
Mutaciones KEEP: [N] | Mutaciones REVERT: [N]

### Mutaciones aplicadas (en orden)
1. [tipo]: [descripción] — Score [X]% → [Y]%
2. [tipo]: [descripción] — Score [X]% → [Y]%

### Mutaciones revertidas
1. [tipo]: [descripción] — Razón: [por qué empeoró]
```

4. **Registrar** en `.planning/APRENDIZAJES.md` las mutaciones más impactantes

## Umbrales de score

| Score | Estado | Acción |
|-------|--------|--------|
| 95-100% | Excelente | Loop terminado, guardar skill |
| 80-94% | Bueno | Continuar, mejoras marginales posibles |
| 60-79% | Regular | Loop activo, priorizar mutaciones de peso alto |
| < 60% | Deficiente | Considerar reescritura antes de iterar |

## Condiciones de salida del loop

| Condición | Acción |
|-----------|--------|
| 95%+ × 3 consecutivas | **Éxito** — guardar y versionar |
| 10 rounds sin alcanzar 95% | **Plateau** — reportar y pedir input humano |
| 3 reverts consecutivos | **Estancamiento** — cambiar estrategia de mutación |
| Score baja 2 rounds seguidos | **Degradación** — revertir al mejor score alcanzado |

## Integración con auto-evolución SWL

```
auto-evolucion-swl detecta skill con bajo rendimiento
  → /swl:autoresearch --skill=[nombre]
  → Loop de mejora iterativa
  → Skill mejorado + changelog
  → consolidador-swl registra la evolución
```

| Componente SWL | Rol en Autoresearch |
|---------------|-------------------|
| `auto-evolucion-swl` | Identifica candidatos para el loop |
| `checklist-calidad` | Base para crear checklists de evaluación |
| `aprendizaje-continuo` | Los instintos alimentan nuevos items del checklist |
| `extraccion-aprendizajes.js` | Captura mutaciones exitosas como aprendizajes |
| `validacion-ci-sistema` | Verifica integridad post-mutación |

## Cuándo NO cargar

- Se quiere mejorar un output de sesión puntual en lugar del SKILL.md persistente — el autoresearch opera sobre el archivo del skill, no sobre el output de una sola invocación.
- El skill tiene score < 60% sin análisis de causa raíz; mejor revisar si la estructura del skill es correcta antes de iterar — el loop puede no converger.
- El objetivo es evaluar un agente (frontmatter, `permisosRed`, capacidades); para eso usar `evaluacion-agentes` o la heurística de `diseno-herramientas-agente`.

## Gotchas / Errores comunes no obvios

- **Múltiples mutaciones aplicadas en una iteración**: el agente "optimiza" cambiando 3 reglas a la vez porque parecen relacionadas. Si el score sube 5%, no se sabe cuál mutación ayudó; si baja, no se sabe cuál causó el daño. Causa: violación de la regla "UNA mutación por iteración". Solución: deshacer todas las mutaciones simultáneas, aplicarlas una por una y evaluar cada una independientemente — el rigor del loop depende de esta atomicidad.
- **Plateau a los 10 rounds con score 78%**: el loop termina por max rounds sin alcanzar 95% y el agente declara "skill no mejorable". Causa: el checklist puede tener ítems redundantes o el caso de prueba no es representativo del uso real. Solución: ante un plateau, revisar primero si el checklist tiene ítems de bajo impacto (peso 1-2) que suman ruido — ajustar el checklist antes de considerar reescritura del skill.
- **REVERT no restaura el estado exacto anterior**: el agente hace el revert a mano editando el SKILL.md y no llega al estado byte-idéntico al pre-mutación. Causa: el revert manual puede introducir diferencias de whitespace o puntuación. Solución: hacer commit del SKILL.md antes de cada mutación — el revert es `git checkout <hash> -- habilidades/<skill>/SKILL.md`, no edición manual.
- **Caso de prueba no representativo del uso real del skill**: el checklist se evalúa con un escenario ideal que siempre pasa desde el baseline. Causa: el caso de prueba fue elegido por conveniencia. Solución: el caso de prueba debe ser el escenario donde el skill falla con más frecuencia según los logs de sesión — un skill que ya pasa el caso ideal no necesita autoresearch.

## Anti-patrones

### Checklists subjetivos — prohibidos

```markdown
# MAL — no evaluable automáticamente
| 1 | El código es elegante | 3 | ??? |

# BIEN — objetivo y verificable
| 1 | Funciones tienen ≤20 líneas | 3 | wc -l por función |
```

### Múltiples mutaciones simultáneas — prohibido

Si cambias 3 cosas y el score sube, no sabes cuál funcionó. Una por iteración.

### Iterar infinitamente — máximo 10 rounds

Si no mejora en 10 rounds, el checklist está mal diseñado o el skill necesita
reescritura fundamental, no iteración incremental.

### Ignorar reverts — son información valiosa

Un revert dice "esta dirección no funciona". Intentar otra estrategia sobre el
mismo item problemático, no repetir la misma mutación.
