The trace is the receipt
Bug report, day two of the feature: "the agent filed a p1 for an npm 503 instead of just rerunning — and why did nobody get paged?" Your move is not to reread the prompt, and it is definitely not to rerun the agent and hope it misbehaves again. Nondeterministic systems don't grant you a repro. Your move is to open the trace.
Run the code. Four dicts, one per step: tool, validator verdict, result, running spend. Reading it top to bottom answers the bug report in about fifteen seconds: the agent did read the log, did see the 503, then proposed escalate — arguably right for a registry outage blocking all of CI — got rejected for missing confirmation, and fell back to open_issue at p1. Nobody got paged because the confirm gate held (working as designed) and the p1 happened because the fallback path doesn't downgrade severity (the actual bug, and it's in your routing logic, not the model).
Without the trace, that same investigation is an afternoon of rereading a chat transcript and speculating about model intent. The transcript can't tell you whether the agent retrieved the wrong data, called the wrong tool, or reasoned badly over good inputs. The trace can — it's the recorded story of one run: what came in, what was decided, what was called, what it cost.
Trace-first is a discipline, not a log level
Three rules, all cheap now and expensive to retrofit:
- The loop writes the trace; humans don't. Every iteration appends its record as a side effect of running — tool, verdict, result, spend. If tracing is a thing someone remembers to add, the run you need traced is the run that didn't have it. In production this is a JSONL file or an OTel span per step; the schema is exactly the dict you just read.
- Record verdicts, not just actions. Step 3 is the most informative line in this trace and nothing executed — a rejected call that never ran. Log only what succeeded and the story reads "read log, opened issue," which hides the entire plot: the agent wanted to page a human and your gate said no. Rejections are evidence of the model's intent colliding with your contract. That collision is usually where the bug lives.
- No secrets in the trace. The trace outlives the run — it lands in log aggregators, bug reports, that Slack thread with a screenshot. Tool results carry log tails; log tails love to carry tokens. Redact at write time, because you don't control who reads it later.
Debug from the trace first, the code second, the prompt third. The order matters: the trace tells you which of the other two to open.