ai-forge

AI Forge Eval

Validación conductual para habilidades y agentes. La puntuación basada en rúbricas (ai-forge-judge) te dice si un artefacto está bien escrito. Eval te dice si funciona.

Funciona para SKILL.md (habilidades) y .agent.md (agentes). Mismo flujo de 5 fases; la Fase 2 de configuración difiere según el tipo de artefacto.

---

Fase 0 — Cargar o Escribir la Suite

OBLIGATORIO — LEE references/eval-suite.md para conocer el formato en disco, el protocolo de activación y la tabla de discriminación de aserciones.

Verifica la existencia de evals/evals.json junto al artefacto.

• Presente — cárgalo y salta a la Fase 2. Añade casos si la cobertura es escasa; nunca reemplaces silenciosamente los existentes, o la tendencia se rompe.
• Ausente — créalo en la Fase 1 y escríbelo en evals/evals.json antes de generar cualquier cosa.

Una suite que solo vive en esta conversación no puede detectar una regresión el próximo mes. Persistirla es lo que marca la diferencia entre una opinión y una prueba.

---

Fase 1 — Escribir Evals

Escribe 2–3 casos de evaluación. Cada evaluación es un prompt realista más 3–5 aserciones.

Prefiere prompts extraídos de una sonda base (ai-forge-create Fase 1b) en lugar de los triggers declarados por el propio artefacto; las aserciones escritas desde el artefacto solo pueden confirmar que hace lo que afirma. Lleva cada captura al campo baseline_failure del escenario.

Para habilidades: prompts que deberían activar la habilidad de forma natural. Las aserciones verifican comportamientos específicos de la habilidad (por ejemplo, "la salida incluye un resumen de la Fase 1", "el formato de la regla NUNCA tiene POR QUÉ y EN VEZ DE ESO").

Para agentes: prompts que cubren el alcance declarado del agente. Las aserciones verifican comportamientos observables: archivos creados, herramientas llamadas, restricciones de tono, límites de alcance (por ejemplo, "no modificó archivos fuera de src/lib/", "abrió un PR", "el mensaje de commit comienza con 'refactor:'").

Reglas de aserciones:

• Verificables: el evaluador puede comprobarlas solo a partir de la salida
• Específicas: "la salida incluye el encabezado 'Fase 1'" es mejor que "la salida está bien estructurada"
• Falseables: debe ser posible que fallen

Registra las evaluaciones:

Evaluación 1: <prompt>
Expectativas:
- <aserción 1>
- <aserción 2>
- <aserción 3>

---

Fase 2 — Generar en Paralelo

Para cada evaluación, genera las ejecuciones con artefacto y de referencia en el mismo mensaje (nunca secuencialmente). En modo benchmark esto se convierte en N pares de prueba por evaluación; consulta el modo Benchmark más abajo.

Ejecución con artefacto: dale el prompt de evaluación. Para habilidades: añade "Usa la habilidad <skill-name> para esta tarea." Para agentes: pega las instrucciones completas del agente como contexto del sistema.

Ejecución de referencia: depende de lo que se mida.

• Artefacto nuevo — mismo prompt de evaluación, sin instrucción de habilidad, sin contexto de agente. Respuesta del asistente simple.
• Mejora de un artefacto existente — primero toma una instantánea de la versión actual (cp -r <ruta> <scratch>/snapshot/), luego apunta la referencia a la instantánea. "Sin artefacto" es el control incorrecto cuando la pregunta es si el cambio ayudó; mide la existencia del artefacto, no la edición.

Captura inmediatamente al completarse: cuando llegue cada notificación de tarea, registra qué ejecución fue (más el índice de prueba en modo benchmark) y lee duration_ms y subagent_tokens de su bloque <usage> — exacto, no estimado. Sin bloque <usage> significa registrar null; nunca sustituyas una estimación de tiempo real. Estos datos existen solo en el momento de la notificación y no se pueden reconstruir después.

Almacena por evaluación: texto de salida with_artifact y baseline, más duration_ms y tokens para cada brazo.

---

Fase 3 — Calificar

LECTURA OBLIGATORIA: agents/assayer.md

Para cada evaluación, invoca al evaluador en ambas salidas. Pasa:

Output: <texto de salida>
Expectativas:
- <aserción 1>
- <aserción 2>

El evaluador devuelve por expectativa:

{ "text": "...", "passed": true, "evidence": "..." }

Calcula pass_rate = pasadas / totales por ejecución. Calcula delta = pass_rate_con_artefacto - pass_rate_referencia.

Luego clasifica cada aserción según cómo se comporta en ambos brazos: pasa en ambos (mide el modelo, no el artefacto), falla en ambos (rota o fuera de alcance), pasa con y falla sin (señal real), falla con y pasa sin (el artefacto está perjudicando), o alta varianza (inestable). Consulta la tabla en references/eval-suite.md. Una suite cuyas aserciones pasan todas en ambos brazos reporta una tasa de aciertos saludable y no te dice nada.

También lee la transcripción, no solo la salida: ¿la ejecución siguió realmente el artefacto, o llegó a la respuesta correcta a pesar de él? El trabajo causado por el artefacto que no produjo nada es un candidato a eliminación.

---

Fase 3b — Revisión Humana

Antes de analizar nada por tu cuenta, pon las salidas brutas frente al usuario.

Llena assets/eval-review.html — sustituye __ARTIFACT_NAME__ y __EVAL_DATA__ (un arreglo JSON de {id, name, prompt, with_artifact, baseline, assertions}) y escríbelo junto a la suite de evaluación. Muéstraselo con una herramienta de entrega de archivos si está disponible; de lo contrario, dale al usuario la ruta. Lee el feedback.json exportado cuando terminen.

La calificación del modelo sobre la salida de su propio artefacto es la señal más débil aquí: un vistazo humano detecta lo que ninguna aserción fue escrita para detectar. Omite solo si el usuario lo rechaza.

---

Fase 4 — Comparar (opcional)

LECTURA OBLIGATORIA: agents/arbiter.md — cargar solo cuando se ejecute la Fase 4.

Ejecuta la Fase 4 cuando: delta > 0.1 en alguna evaluación, o las tasas de aciertos entran en conflicto entre evaluaciones.

Omite cuando: las tasas de aciertos son idénticas, o el usuario solo solicitó calificaciones.

Entrada del árbitro: Salida A (sin etiquetar), Salida B (sin etiquetar), lista de expectativas. Registra cuál era cuál para la Fase 5.

El árbitro devuelve: puntuación de contenido (1–5), puntuación de estructura (1–5), ganador (A/B/empate), justificación, fortalezas/debilidades por lado.

Puerta de envío al comparar dos versiones: envía solo si la nueva versión gana o empata en todos los escenarios, y gana al menos uno. Una versión que gana por mucho en un caso y pierde en otro ha intercambiado un fallo por uno diferente — eso no es una mejora, y el delta agregado lo ocultará.

---

Fase 5 — Analizar + Informar

LECTURA OBLIGATORIA: agents/refiner.md — cargar solo si se ejecutó la Fase 4.

Si se omitió la Fase 4: ve directamente a la tabla de benchmark.

Entrada del refinador: salida del árbitro + mapeo de etiquetas { "A": "with_artifact", "B": "baseline" } (o invertido). El refinador explica por qué el ganador venció al perdedor y muestra 1–3 mejoras priorizadas.

Renderiza la tabla de benchmark — una fila por evaluación más una fila Promedio, columnas Evaluación | con_artefacto | referencia | delta | duración_ms (con / base), conteos de aciertos y porcentajes por brazo. Añade cualquier aserción no discriminante o perjudicial señalada en la Fase 3, luego las sugerencias de mejora del refinador si se ejecutó.

Si el delta es negativo en alguna evaluación, marca: "El artefacto puede estar perjudicando el rendimiento — revisa la redacción del trigger o las restricciones de alcance."

---

Fase 6 — Verificación de Trigger

Las evaluaciones conductuales responden "¿funciona cuando se invoca?". Esto responde "¿se invoca?" — el fallo más común, e invisible para todas las fases anteriores.

Ejecuta cuando la suite tiene un bloque triggers, u ofrécelo después de la Fase 5. OBLIGATORIO — LEE references/eval-suite.md para conocer el protocolo, la división 60/40 de retención y el estándar de calidad de consulta. NO lo cargues para una ejecución puramente conductual.

Informa la precisión y la exhaustividad por división (entrenamiento y retenido) más los fallos específicos y los falsos positivos. Baja exhaustividad con alta precisión significa que la descripción es demasiado estrecha — amplíala. Lo contrario significa que está tomando tareas adyacentes — añade triggers negativos.

---

Modo Benchmark

Activa cuando el usuario pida hacer benchmark, rastrear regresiones, o decidir en función de la tendencia. El modo benchmark extiende las cinco fases con pruebas repetidas y un almacén de tendencias persistente.

LECTURA OBLIGATORIA: references/benchmarking.md antes de ejecutar — el protocolo de prueba, las fórmulas de agregación, los umbrales de decisión y los esquemas de resultados de prueba + benchmark.json están allí. NO lo cargues para una evaluación simple de una sola ejecución.

• Pruebas — cada evaluación se ejecuta N veces (por defecto 3). Por evaluación, genera todos los N pares de prueba (2N subagentes) en UN mensaje, procesa las notificaciones de esa evaluación capturando <usage> como en la Fase 2, luego pasa a la siguiente evaluación. Nunca generes todas las pruebas de todas las evaluaciones a la vez.
• Agregar — node scripts/aggregate-benchmark.cjs --trials <scratch.json> --prior benchmarks/<nombre-artefacto>.json --artifact <ruta> devuelve la media/desviación estándar por evaluación, banderas de inestabilidad y discriminación, deltas con respecto a la ejecución anterior, y un veredicto de puerta. Si no se puede ejecutar (sin node, script faltante, error de uso), reporta los resultados brutos por prueba con ⚠ no se pudo agregar — validador no disponible: <motivo> y no calcules manualmente un veredicto de puerta; un veredicto de puerta es una afirmación sobre significancia estadística y no debe estimarse. Un veredicto de FALLO siempre bloquea.
• Persistir — guarda el payload devuelto en benchmarks/<nombre-artefacto>.json (commiteado) como la nueva línea de base de tendencia.
• Informar — tabla de la Fase 5 con columnas de media±desviación estándar más el veredicto de puerta. En caso de fallo de puerta, el veredicto es "regresado — no listo".

---

NUNCA

• NUNCA generes las ejecuciones con artefacto y de referencia de una prueba secuencialmente En su lugar: Ambos brazos de cada prueba en el mismo mensaje. En modo benchmark, todos los N pares de prueba para una evaluación van en un mensaje; diferentes evaluaciones pueden agruparse secuencialmente. Por qué: Brazos secuenciales serializan la retroalimentación paralela; pero generar las pruebas de todas las evaluaciones a la vez inunda las notificaciones y hace que la captura de <usage> por llegada sea poco fiable.

• NUNCA pospongas la captura de uso hasta que otras ejecuciones terminen En su lugar: Lee el bloque <usage> (duration_ms, subagent_tokens) de cada notificación en el momento en que llega. Por qué: Los datos de <usage> existen solo en el momento de la notificación y no se pueden reconstruir después.

• NUNCA reportes una sola prueba como un benchmark En su lugar: Ejecuta al menos N=3 pruebas para que la media y la desviación estándar sean significativas. Por qué: Una tasa de aciertos solitaria parece precisa pero oculta la inestabilidad — una habilidad que realmente pasa un tercio de las veces puede leerse como 100% o 0% en una sola prueba.

• NUNCA debilites un escenario en el que una ejecución con artefacto falló En su lugar: Fortalece el cuerpo hasta que la ejecución pase el escenario tal como está escrito. Por qué: El escenario es el registro de un fallo real. Suavizarlo hace que la evaluación se vuelva verde mientras el fallo para el que fue construida sobrevive intacto.

• NUNCA ajustes una descripción contra las consultas de trigger retenidas En su lugar: Itera sobre la división de entrenamiento; mira la retenida solo para seleccionar la versión final. Por qué: Una descripción ajustada contra su propio conjunto de prueba puntúa bien y generaliza peor — pierdes la única estimación no sesgada que tenías.

• NUNCA escribas aserciones subjetivas ("la salida es clara", "bien formateada", "exhaustiva") En su lugar: Verificable a partir del texto: "la salida incluye el encabezado 'Fase 1'", "ninguna regla NUNCA carece de una cláusula POR QUÉ" Por qué: Las aserciones subjetivas no proporcionan una verdad fundamental al evaluador; aprobar/fallar se vuelve arbitrario e irrepetible.

• NUNCA uses prompts diferentes para las ejecuciones con artefacto y de referencia En su lugar: Prompt idéntico — solo difiere la instrucción del artefacto. Por qué: La variación de prompts confunde el delta; mide la calidad del prompt, no el efecto del artefacto.

• NUNCA aceptes la salida del evaluador con nombres de campo no estándar En su lugar: Exige text, passed, evidence exactamente — rechaza name, met, details u otros. Por qué: La agregación de la Fase 5 depende de nombres de campo exactos; nombres incorrectos silenciosamente producen tasas de aciertos incorrectas.