Reading the Audit Trail
When a run goes sideways, the artifacts are your trace. Debug it like an incident: evidence first.
A failed agent run leaves a complete trail: the task list shows where it stalled, the implementation plan shows what it believed, terminal output shows what actually happened, and the browser recording shows what a user would have seen. Debugging an agent run is incident analysis — reconstruct, find the divergence, fix the cause.
Reconstruct the timeline
Open the conversation and walk the artifacts in order: brief → plan → task list progress → terminal output → walkthrough (or the absence of one).
Questions in order: What did I ask? What did it plan? Where did progress stop? What did the last command actually print?VerifyYou can name the exact step where reality and plan parted ways.Find the belief that broke
Every bad run has a divergence point — the plan assumed a test DB existed, the brief never said which package manager, the page object changed shape. The artifact trail makes the wrong belief visible.
Look for the earliest artifact that contains the wrong assumption — that's the fix site, not the code the agent wrote afterward.VerifyYou've written one sentence: "The run failed because it believed X, and X was false because Y."Fix the input, then persist the lesson
Hand-patching the diff fixes one run. Fixing the brief fixes this task. Adding the correction to the knowledge base fixes the whole class of future tasks.
Add knowledge: "Integration tests need `docker compose up -d db` first; the suite does NOT self-provision."VerifyThe retried run passes the divergence point — and next month's agents never hit it.