Referencia · Playbook de análisis de error

El bucle

trazas reales
    ↓  open coding      · una frase por traza, sin categorías previas
notas crudas
    ↓  axial coding     · agrupa en 5–8 modos de fallo; nombra la CAUSA
taxonomía
    ↓  conteo           · frecuencia por modo, ordenada
lista priorizada
    ↓  evals            · un test por modo, empezando por el más frecuente
cifra defendible
    ↓  itera            · vuelve a trazas. El bucle no termina.

Reglas

Regla	Por qué
Lee las trazas tú, a mano	Quien lee las trazas es quien entiende el sistema. Delegarlo es delegar la comprensión.
Nunca categorices durante el open coding	Las categorías previas te hacen ver los fallos que esperabas y ciegan los que no.
Nombra la causa, no el síntoma	«Los tests fallan» no es un modo de fallo. «El agente no lee tests existentes antes de escribir» sí.
5–8 modos, ni más ni menos	Menos = cajón de sastre inútil. Más = no has agrupado, has renombrado.
Elige bien la unidad de análisis	Hay fallos invisibles por traza que solo aparecen por sesión, por wave o por semana.
Evals después, nunca antes	Un eval sin análisis de error previo testea un bug que nunca has visto.
Persiste las trazas desde el día uno	Un harness que no guarda trazas no se puede evaluar. Es un fallo de arquitectura, no de proceso.

Anti-patrones

Si te ves haciendo esto…	…estás en un callejón sin salida
Un rubric de 5 criterios y una nota media de 4,2/5	Métrica de vanidad. No te dice qué arreglar el lunes.
Un LLM-as-judge sin haber leído trazas antes	Estás automatizando un juicio que aún no tienes.
Un LLM-as-judge sin medir su acuerdo con tu juicio	Un juez no alineado es un generador de números aleatorios caro.
Medir solo «éxito / fracaso»	Sin taxonomía, un 73% no se convierte en un plan de trabajo.
Optimizar el prompt antes de conocer el modo de fallo	La mayoría de fallos de agentes se arreglan en el harness, no en el prompt.

Glosario mínimo

Término	Definición operativa
Traza	El registro completo de una ejecución: entrada, cadena de llamadas al modelo y a herramientas, salida. Si no la persistes, no existe.
Open coding	Anotar en lenguaje libre qué falló en cada traza, sin taxonomía previa. Prestado de la investigación cualitativa.
Axial coding	Colapsar esas anotaciones en un conjunto pequeño de modos de fallo que emergen de los datos.
Modo de fallo	Una causa recurrente, nombrada de forma accionable. La unidad de trabajo del análisis.
Fallo plausible	El agente falla de una forma que parece un éxito. El más caro: no dispara alarmas y envenena las métricas.
LLM-as-judge	Usar un modelo para puntuar salidas. Solo vale si has medido su acuerdo con tu juicio experto sobre un conjunto etiquetado a mano.
Alineamiento del juez	El % de acuerdo entre el juez automático y el humano. Sin esta cifra, el juez no es una métrica: es una opinión.
Unidad de análisis	El grano al que cuentas fallos: llamada, traza, sesión, wave, semana. Cambiarla revela fallos distintos.
Baseline	La cifra antes de tu cambio. Sin baseline no hay mejora, hay anécdota. Fever la pide por su nombre en la oferta.