Autoresearch: Self-Improving Skills

Las evals son la UNICA forma de medir si el skill mejoro. Sin buenas evals, autoresearch es ruido.

Reglas de evals:

1. SIEMPRE binarias (si/no, pass/fail). NUNCA escalas Likert (1-7). La variabilidad compuesta mata la senal.
2. 3-6 criterios por skill. Menos de 3 = no captura calidad. Mas de 6 = el modelo "gamea" el examen.
3. Nunca demasiado estrechos. "Maximo 50 palabras" hace que el modelo optimice para brevedad, no calidad.
4. Cubrir dimensiones ortogonales. Cada criterio mide algo DIFERENTE (formato, contenido, tono, precision, etc).

1.3 Definir parametros

1.4 Crear branch y baseline

git checkout -b autoresearch/<skill-name>

• Leer el SKILL.md actual del skill target
• Copiar el SKILL.md a <skill>/SKILL.md.backup (seguridad)
• Inicializar <skill>/autoresearch-results.tsv con header:

iteration	score	max_score	pct	status	changes_summary

• Correr la primera evaluacion como baseline (iteration 0, status: baseline)
• Confirmar con el usuario: "Baseline: X/Y (Z%). Criterios: [lista]. Arranco?"

Una vez el usuario confirma, NO PARAR.

Fase 2: El Loop (autonomo)

"El humano puede estar dormido. NUNCA pausar para preguntar. NUNCA pedir confirmacion. Trabajar indefinidamente hasta ser interrumpido manualmente." -- Karpathy

El ciclo exacto:

LOOP (hasta max_iterations o target_score):

  1. ANALIZAR — Leer resultados previos. Que fallo? Que patron emerge?

  2. HIPOTESIS — Formular UNA hipotesis clara:
     "Si cambio X en el prompt, deberia mejorar Y porque Z"

  3. MUTAR — Editar el SKILL.md del skill target
     - UN cambio por iteracion (aislamiento de variables)
     - Cambios en: instrucciones, ejemplos, restricciones, formato, orden
     - NUNCA tocar el frontmatter (name, description, allowed-tools)
     - NUNCA agregar criterios de eval al prompt (eso es gaming)

  4. COMMIT — git add + git commit ANTES de correr
     Mensaje: "autoresearch(<skill>): iter N — <hipotesis corta>"

  5. GENERAR — Correr el skill N veces con inputs variados
     - Usar inputs representativos del uso real del skill
     - Variar los inputs entre iteraciones (no siempre el mismo)
     - Capturar cada output

  6. EVALUAR — Para cada output, aplicar cada criterio (si/no)
     - Score = total de "si" / max_score
     - Si el skill produce outputs VISUALES: usar Claude vision para evaluar
     - Si el skill produce TEXTO: evaluar con criterios directos
     - Si el skill produce DATOS/QUERIES: evaluar precision y completitud

  7. DECIDIR:
     - Si score > best_score -> STATUS: keep
       -> El commit se queda. Actualizar best_score.
     - Si score <= best_score -> STATUS: discard
       -> git reset --hard HEAD~1 (revertir al commit anterior)
     - Si el skill crasheo -> STATUS: crash
       -> Intentar fix trivial. Si no, revertir y continuar.

  8. REGISTRAR — Append a autoresearch-results.tsv:
     iteration	score	max_score	pct	status	changes_summary

  9. REPETIR — Ir al paso 1. No parar. No preguntar.

Reglas del loop

• UN cambio por iteracion. Si cambias 3 cosas y mejora, no sabes cual ayudo.
• Inputs variados. No optimizar para UN input. Usar al menos 3 inputs diferentes por ciclo.
• Simplicidad > complejidad. Si el prompt crece 50 lineas y mejora 2%, no vale. Si ELIMINAR lineas mantiene el score, MEJOR (prompt mas corto = mas robusto).
• No gaming. NUNCA copiar los criterios de eval textualmente al prompt. Eso es un estudiante que memoriza el examen.
• Crash tolerance. Un crash no es el fin. Log it, revert, try different approach.
• Context management. NUNCA dejar que outputs largos inunden el contexto. Si el skill genera archivos, leer solo lo necesario para evaluar.

Criterio de simplicidad (de Karpathy)

"Mejora pequena (0.001) con 20 lineas de codigo feo = NO vale la pena. Mejora pequena (0.001) por ELIMINAR complejidad = SIEMPRE vale la pena."

Traducido a skills:

• Agregar 10 instrucciones al prompt para subir 5% = cuestionable
• Reescribir 1 instruccion confusa y subir 5% = excelente
• Eliminar instrucciones redundantes manteniendo el score = excelente

Fase 3: Reporte

Cuando se alcanza target_score o max_iterations:

3.1 Generar resumen

## Autoresearch Report: <skill-name>

**Baseline:** X/Y (Z%)
**Final:** X/Y (Z%)
**Mejora:** +N% en M iteraciones
**Costo estimado:** ~$X USD
**Iteraciones:** N total (K kept, D discarded, C crashed)

### Cambios que mejoraron:
1. Iter 3: <cambio> -> +5%
2. Iter 7: <cambio> -> +3%
...

### Cambios que NO mejoraron:
1. Iter 2: <cambio> -> -2% (descartado)
...

### Prompt final vs original:
<diff resumido>

3.2 Merge o esperar

• Mostrar el reporte al usuario
• Si aprueba: git checkout main && git merge autoresearch/<skill>
• Si quiere mas: continuar el loop
• El autoresearch-results.tsv queda como historial permanente

Tipos de Evaluacion por Output

Texto (posts, reportes, descripciones)

Criterio 1: El output contiene la informacion clave solicitada? (si/no)
Criterio 2: El tono es apropiado para el contexto? (si/no)
Criterio 3: La estructura es clara y facil de leer? (si/no)
Criterio 4: No hay informacion inventada o incorrecta? (si/no)

Visual (diagramas, imagenes, UI)

Criterio 1: Todo el texto es legible y sin errores? (si/no)
Criterio 2: Los colores y contraste son adecuados? (si/no)
Criterio 3: El layout es claro y organizado? (si/no)
Criterio 4: Comunica la idea sin ambiguedad? (si/no)

Data/Queries (SQL, APIs, servicios)

Criterio 1: El query/llamada retorna datos sin error? (si/no)
Criterio 2: Los resultados son correctos? (si/no)
Criterio 3: El formato de salida es legible? (si/no)
Criterio 4: Maneja edge cases correctamente? (si/no)

Codigo (componentes, funciones, features)

Criterio 1: El codigo compila/funciona sin errores? (si/no)
Criterio 2: Sigue los patrones del proyecto (Feature-First, etc)? (si/no)
Criterio 3: No introduce vulnerabilidades de seguridad? (si/no)
Criterio 4: Es mantenible y legible? (si/no)

Integracion con Skill Creator

Si el skill target NO tiene evals definidas, usar skill-creator para:

1. Generar eval set inicial
2. Definir expectations
3. Correr validacion como herramienta de medicion

Autoresearch NO reemplaza a skill-creator. Skill-creator CREA skills. Autoresearch los OPTIMIZA despues de creados.

Limites de Seguridad

Quick Start

Usuario dice: "Optimiza el skill de landing"

1. Leo landing/SKILL.md completo
2. Propongo 4 criterios binarios (basado en el tipo: texto + codigo)
3. El usuario confirma o ajusta
4. Creo branch autoresearch/landing
5. Corro baseline (5 ejecuciones, evaluo, score X/20)
6. Muestro baseline, usuario dice "dale"
7. Loop autonomo hasta target o max_iterations
8. Reporte final -> usuario decide merge