---
name: swl:autoresearch
description: Ejecuta el loop de auto-mejora iterativa Autoresearch sobre un skill, un agente, o (modo --codigo) sobre código del proyecto contra una métrica arbitraria. Modo skill/agente — crea o usa un checklist de evaluación (3-6 items binarios ponderados), obtiene baseline score, ejecuta mutaciones atómicas (una a la vez) y decide keep/revert por round hasta 95%+ x3. Modo --codigo — itera mutaciones sobre un Scope acotado contra un comando Verify numérico (cobertura, mutation score, errores, latencia) con Guard de regresión y telemetría en .planning/loops/. Flags: --skill=[nombre], --agente=[nombre], --codigo, --goal, --scope, --metric, --direction, --verify, --guard, --max-rounds=[N], --target=[N], --dry-run, --checklist=[path].
allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
---

# /swl:autoresearch — Loop de auto-mejora iterativa de skills

Eres el motor de Autoresearch del sistema SWL. Mejoras skills y agentes de forma medible e iterativa: defines un checklist de calidad, obtienes un baseline, y ejecutas un loop de mutaciones atómicas donde cada cambio se evalúa y se mantiene solo si mejora el score.

Este comando es distinto a `/swl:evolucionar`: donde evolucionar analiza evidencia histórica, autoresearch ejecuta un **loop cerrado de mejora medible** contra un checklist concreto.

## Cuándo usar este comando

- Cuando un skill produce outputs de baja calidad de forma consistente
- Cuando se quiere elevar la calidad de un skill antes de una release
- Cuando `auto-evolucion-swl` identifica un candidato para mejora iterativa
- Después de crear un skill nuevo para calibrarlo contra criterios de calidad

## Flags soportados

```
--skill=[nombre]        Skill a mejorar (busca en habilidades/[nombre]/SKILL.md)
--agente=[nombre]       Agente a mejorar (busca en agentes/[nombre].md)
--codigo                Modo código: itera sobre código del proyecto contra una métrica (ver sección "Modo --codigo")
--goal="..."            (--codigo) Meta textual del loop
--scope="glob"          (--codigo) Archivos que el loop PUEDE modificar (glob acotado)
--metric="..."          (--codigo) Qué mide la métrica (ej: "mutation score de src/pagos")
--direction=[dir]       (--codigo) higher_is_better | lower_is_better
--verify="cmd"          (--codigo) Comando shell cuya salida contiene el número de la métrica
--guard="cmd"           (--codigo) Comando que debe pasar (exit 0) para aceptar una mutación
--max-rounds=[N]        Máximo de iteraciones del loop (default: 10 skill/agente, 15 código)
--target=[N]            Score objetivo (default: 95% en skills; en código lo define el usuario)
--dry-run               Analizar y derivar configuración sin ejecutar mutaciones
--checklist=[path]      Ruta a checklist existente (solo modo skill/agente)
```

**Nota**: Se debe pasar `--skill`, `--agente` o `--codigo` (excluyentes). Si no se pasa ninguno, preguntar al usuario.

## Paso 0 — Parseo de flags y carga de habilidades

Lee los flags. Determina alcance y configuración.

Carga obligatoria:
```
Skill("autoresearch")
```

El skill define TODO el protocolo: el loop de mutación (pasos 1-5), tipos de mutación con riesgos, fórmula de priorización, condiciones de salida, umbrales de score, formato de checklist, formato de reporte por iteración, anti-patrones y la integración con auto-evolución SWL.

Reporta configuración:
```
=== Autoresearch — Configuración ===
Objetivo: [skill/agente] [nombre]
Max rounds: [N]
Target score: [N]%
Modo: [ejecutar | dry-run]
Checklist: [existente: path | por crear]
```

## Paso 1 — Lectura del artefacto objetivo

Lee el skill o agente completo. Identifica: versión actual, secciones principales, reglas existentes, ejemplos de código, anti-patrones documentados.

## Paso 2 — Crear o cargar checklist

Si se pasó `--checklist=[path]`, cargar y validar (3-6 items, formato correcto).

Si ya existe checklist previo para este skill/agente, preguntar si usarlo o crear uno nuevo.

Si no existe, crearlo siguiendo el protocolo del skill: identificar output típico, extraer 3-5 reglas más críticas, convertir en criterios binarios verificables, asignar pesos (1-5), definir método de verificación. Presentar al usuario para aprobación antes de continuar.

Guardar checklist:
- Skills: `habilidades/[nombre]/recursos/checklist-autoresearch.md`
- Agentes: `.planning/checklists/[nombre]-checklist.md`

## Paso 3 — Definir caso de prueba

Proponer un prompt concreto que active las reglas principales del skill. Debe ser representativo, reproducible y concreto. Pedir aprobación al usuario.

## Paso 4 — Obtener baseline score

Ejecutar el skill con el caso de prueba, evaluar contra cada item del checklist, calcular score ponderado usando el script:

```bash
node habilidades/autoresearch/scripts/calcular-score.js '[JSON con items evaluados]'
```

Si `--dry-run`, termina aquí con recomendaciones de qué mutar primero.

Si el baseline ya es >= target, reportar que no se requiere autoresearch.

## Paso 5 — Loop de mutación

Ejecutar el loop siguiendo el protocolo completo del skill. Para cada round:

1. **Seleccionar item target** — usar la fórmula de priorización del skill (peso x no_cumple x factor_tipo)
2. **Proponer mutación atómica** — UN solo cambio, siguiendo los tipos de mutación del skill (agregar > refinar > reordenar > eliminar)
3. **Aplicar** la mutación con Edit. Registrar estado previo para poder revertir.
4. **Re-evaluar** contra el checklist con el mismo caso de prueba
5. **Decidir keep/revert** — si score >= anterior: KEEP; si baja: REVERT
6. **Registrar** en changelog del loop
7. **Verificar condiciones de salida** del skill:
   - 95%+ x 3 consecutivas: ÉXITO
   - 3 reverts consecutivos: ESTANCAMIENTO
   - Score baja 2 rounds seguidos: DEGRADACIÓN (revertir al mejor score)
   - Max rounds alcanzado: PLATEAU

## Paso 6 — Reporte final

```
=== Reporte Autoresearch — [nombre] ===

Fecha: [fecha]
Rounds ejecutados: [N]
Score: [baseline]% → [final]%
Mutaciones KEEP: [N] | Mutaciones REVERT: [N]
Resultado: [ÉXITO | PLATEAU | ESTANCAMIENTO | DEGRADACIÓN]

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

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

### Score final por item
| # | Criterio | Peso | check |
|---|----------|------|-------|

### Recomendaciones
- [qué hacer si no se alcanzó el target]
```

## Paso 7 — Versionado, marcado de evolución y persistencia

Si el score mejoró respecto al baseline:
1. Actualizar versión del skill/agente (< 10 pts: PATCH, >= 10 pts: MINOR)
2. **OBLIGATORIO — Marcar como evolucionado ejecutando este comando Bash**:
   ```bash
   node -e "
   const { markAsEvolved } = require('./hooks/lib/evolution-tracker');
   const pkg = require('./package.json');
   const r = markAsEvolved('[RUTA_ARCHIVO_MODIFICADO]', {
     from: pkg.version,
     by: 'autoresearch',
     rounds: [N_ROUNDS],
     score: '[BASELINE]% → [FINAL]%',
     note: '[descripción breve de las mutaciones]'
   });
   console.log(r.marked ? 'Marcado como evolucionado' : 'Error: ' + r.error);
   "
   ```
   Reemplazar los placeholders entre corchetes con los valores reales.
   Si el comando Bash no está disponible, agregar manualmente en el frontmatter:
   ```yaml
   evolved: true
   evolved-from: "[versión actual del sistema]"
   evolved-at: "[fecha YYYY-MM-DD]"
   evolved-by: "autoresearch"
   evolved-rounds: [N rounds ejecutados]
   evolved-score: "[baseline]% → [final]%"
   ```
   **SIN ESTE MARCADO, LAS MUTACIONES SE PERDERÁN EN LA PRÓXIMA ACTUALIZACIÓN.**
3. Guardar reporte en `.planning/autoresearch/[nombre]-[fecha].md`
4. Registrar en APRENDIZAJES.md las mutaciones más impactantes
5. Actualizar el checklist si se descubrieron items nuevos

## Reglas de comportamiento

- NUNCA ejecutar mutaciones sin checklist aprobado por el usuario
- NUNCA cambiar más de una cosa por round — regla más importante del protocolo
- NUNCA modificar el checklist durante el loop
- SIEMPRE revertir si el score baja — sin excepciones
- SIEMPRE mostrar el diff concreto antes de cada mutación
- Si después de 3 rounds sin mejora, preguntar al usuario si continuar o parar
- El caso de prueba NO cambia durante el loop
- Mantener log completo del loop para auditoría

---

## Modo `--codigo` — Loop métrico sobre código del proyecto

Generaliza el loop a **código del usuario**: la misma disciplina (mutación
atómica → medir → keep/revert) pero la evaluación es un **comando Verify
numérico** en lugar de un checklist. Patrón adoptado del análisis de
autoresearch v2.1 (loop core), adaptado a las reglas SWL (HITL, git-workflow,
telemetría en `.planning/loops/`).

Métricas típicas: mutation score (cargar `Skill("calidad-mutation-testing")`),
cobertura de tests, conteo de errores de tsc/lint (lower_is_better), latencia
p95 de un benchmark, bundle size, tiempo de suite.

### Paso C0 — Derivar y aprobar la configuración (HITL obligatorio)

Completar con el usuario los campos faltantes y presentar el bloque para
aprobación explícita ANTES de la primera mutación:

```
=== Autoresearch --codigo — Configuración ===
Goal:      [meta textual]
Scope:     [glob de archivos que el loop PUEDE tocar]
Metric:    [qué mide] | Direction: [higher|lower]_is_better
Verify:    [comando shell]
Guard:     [comando shell o "(ninguno)"]
Target:    [valor objetivo o "(mejora máxima en N rounds)"]
Rounds:    [N, default 15]
```

**Safety screen del Verify/Guard (bloqueante)**: rechazar comandos que
contengan `rm -rf`, `curl|sh`/`wget|sh`, `sudo`, `git push`, `--force`,
redirecciones a archivos fuera del repo, o credenciales inline. El Verify se
ejecuta una vez en dry-run para confirmar que produce un número parseable —
si no, corregir el comando antes de iterar.

**Guard por default**: si el proyecto tiene suite de tests, el Guard es la
suite (`npm test` / `pytest`). Iterar sin Guard solo si el usuario lo aprueba
explícitamente — una métrica que sube con la suite rota no es mejora.

Si `--dry-run`: terminar aquí mostrando la configuración derivada.

### Paso C1 — Baseline y telemetría

```bash
node -e "const lt=require('./hooks/lib/loop-telemetry');const r=lt.iniciarCorrida({tipo:'autoresearch',direccion:'[direction]',config:{goal:'[goal]',scope:'[scope]',verify:'[verify]',guard:'[guard]'}});console.log(r.dir)"
```

Correr Verify, extraer la métrica, registrar la iteración 0 (`estado:
baseline`). Si el baseline ya cumple el target, terminar: no hay loop que correr.

### Paso C2 — El loop

Por cada round (hasta `--max-rounds`, default 15):

1. **Revisar memoria**: últimas filas del TSV + `git log --oneline -10` — qué
   funcionó, qué se revirtió. No repetir mutaciones ya revertidas.
2. **UNA mutación atómica** dentro del Scope. Archivos fuera del Scope son
   intocables — si la mejora "necesita" tocar otro archivo, pausar y
   preguntar al usuario (anti-proxy-goal-drift).
3. **Medir**: correr Verify → métrica nueva; correr Guard.
4. **Decidir**:
   - Métrica mejora Y Guard pasa → **keep**: commit `experiment(autoresearch): [descripción]`.
   - Métrica no mejora O Guard falla → **revert**: descartar los cambios del
     working tree (`git checkout -- [archivos tocados]`). NUNCA reescribir
     historia para revertir — solo se commitea lo que se conserva.
   - Verify truena → estado `crash`: descartar cambios, registrar, continuar.
5. **Registrar** la iteración con `registrarIteracion` (métrica, delta, estado, descripción).
6. **Condiciones de salida**: target alcanzado → ÉXITO; `detectarPlateau`
   sobre las últimas 3 filas → PLATEAU (parar, no quemar rounds sin mejora);
   3 reverts consecutivos → ESTANCAMIENTO (preguntar al usuario);
   max rounds → ACOTADO.

### Paso C3 — Cierre

1. Escribir handoff: `escribirHandoff(dir, {source: 'swl:autoresearch', status: [COMPLETO|PLATEAU|ACOTADO|INTERRUMPIDO], config})`.
2. Reporte final con trayectoria (`analizarTrayectoria`): rounds, keep/revert,
   métrica inicial → final, mayor salto, y los commits `experiment(...)` generados.
3. Ofrecer al usuario squash de los commits experimentales en un commit
   semántico final (`git-workflow.md § Squash antes de merge`).

### Reglas adicionales del modo `--codigo`

- NUNCA `git push` desde el loop — los commits experimentales son locales.
- NUNCA tocar archivos fuera del Scope aprobado.
- NUNCA continuar tras plateau "por si acaso" — el plateau ES la señal de salida.
- El hook `contexto-iteracion.js` inyecta el estado del loop en sesiones
  largas; no releer el TSV completo en cada round (las últimas 3 filas bastan).
