a builder's codex
codex · operators · Hamel Husain · ins_husain-triage-before-eval-tooling

Teams must annotate raw LLM traces to discover failure modes before applying automated evaluation

By Hamel Husain · Independent AI consultant and researcher · 2026-08-15 · essay · Evals Skills for Coding Agents

Tier B · TL;DR
Teams must annotate raw LLM traces to discover failure modes before applying automated evaluation

Claim

Applying automated evaluation before a team has mapped its own failure modes produces metrics that optimize for the wrong signals. The correct sequence is: annotate raw traces first, let annotation clusters reveal named failure modes, then automate.

Mechanism

Most teams reach for eval automation early. They build a rubric, select a judge model, and produce scores. The scores reveal that something is wrong but not what kind of thing. Each attempt to fix the rubric adds noise without closing the gap.

Husain's error-discovery workflow reverses the order. A practitioner gives an agent a file of raw LLM outputs or traces. The agent builds a lightweight review application with intelligent sampling. As the practitioner annotates examples, the agent groups the annotations into named failure modes and surfaces similar cases automatically. The practitioner ends the session with a typed taxonomy of what is going wrong and why, not just a score.

A start routing skill handles the first decision. The agent reads the practitioner's situation and directs them to either an eval-audit path (if an existing eval pipeline already exists) or the error-discovery path (if only raw, unanalyzed traces exist). This prevents teams from jumping to automation when they have no failure taxonomy yet.

Conditions

Holds when: a team has raw traces or LLM outputs but no clear taxonomy of failure modes. Holds when eval scores are declining but the team cannot articulate which failure mode is driving the change.

Fails when: the team already has a well-tested, named taxonomy from prior annotation rounds. In that case, jumping to automation is the correct move.

Evidence

Husain added two new skills to "Evals Skills for Coding Agents" in an August 2026 update. The error-discovery skill embeds annotation-driven failure mode discovery directly into an agent workflow. The start routing skill applies triage logic before any tooling runs: it reads the practitioner's situation and selects the correct entry point. Both skills address the same underlying problem. Practitioners apply automation before they understand what they are measuring, and the downstream metrics reflect that confusion.

Signals

Counter-evidence

The approach requires a practitioner willing to do manual annotation work before seeing automated results. Teams under deadline pressure may skip the annotation phase and proceed to automation even knowing the taxonomy is incomplete. The failure mode taxonomy produced by one annotator may not generalize to the full distribution of production traces.

Cross-references

Open the interactive view → View original source → Markdown source →