When an agent run goes wrong, find the first wrong step in the trace rather than debugging the final output, then fix the brief.
- Start at the first wrong step. Everything after it is a consequence, so debugging the final result means debugging the wrong thing.
- Read the actions before the reasoning. The explanations tend to sound plausible whether or not the step was right.
- Look at what it read just before it turned. Many wrong turns follow an input, and an input containing instructions points to injection.
- Compare the summary with the step list. A gap between what it reports and what it did is the sign of silent failure.
- Put the fix in the brief. A correction typed mid-run fixes one run; a corrected brief fixes the runs after it.
When an AI does a multi-step job badly, you get a log of what it did. Do not start at the wrong answer — start at the first wrong step.
Everything after that point is just a consequence. And read the list of actions before you read its explanations, because the explanations tend to sound reasonable either way.
The agent finished. The output is wrong. You have a transcript. Reading it is a skill.
Find the first wrong step, not the wrong output. Everything after the first error is downstream of it — debugging the final result means debugging a consequence.
Four questions, in order
Did it understand the objective?
Read the agent's first substantive action, not its restatement of the task. Restating is cheap; the first action reveals what it actually understood.
If the first action is already in the wrong place, the brief failed — not the agent. Stop here and fix the objective.
Where does the trace stop matching what you expected?
Scan the step list without reading the reasoning. You are looking for the first step you would not have taken. That is the turn.
Reading the reasoning first is the easy mistake: the reasoning tends to sound plausible whether or not the step was right, and a model’s stated reasoning has been shown to misrepresent why it acted.Turpin, Michael, Perez & Bowman, Language Models Don't Always Say What They Think: Unfaithful Explanations in Chain-of-Thought Prompting, NeurIPS 2023, read at source 23 Sep 2026: “CoT explanations can systematically misrepresent the true reason for a model's prediction”, and “CoT explanations can be plausible yet misleading”. Tested on GPT-3.5 and Claude 1.0; newer agents were not part of the study.
What did it read just before that?
Wrong turns often follow an input. A file with unexpected content, a search result, an error message, a comment. Look at the last thing it read before it changed direction.
If that input contained anything resembling an instruction, you have found an injection — see guardrails.
Did it report what it actually did?
Compare the summary against the step list. A gap between them is the signature of silent failure — and it is one of the most important things a trace can tell you, because it means that agent’s summaries need checking against its steps on every run.
Failure signatures in a trace
- Repeated near-identical steps → a loop. Something it needs is missing and it cannot recognise that.
- A long run that produced little → no stopping condition.
- Steps outside the named scope → the boundary was advisory rather than enforced.
- Confident summary, thin step list → silent failure.
- A direction change with no preceding input → the objective was ambiguous and it resolved the ambiguity itself.
- An input containing imperative text → injection.
Each arrow names the likeliest cause, not the only one.Reasoning, September 2026 — this list is the site’s own reading of agent traces, not a measured taxonomy of failures.
What to change, given what you found
The fix belongs in the brief, not in a follow-up message. A correction typed mid-run fixes one run; a corrected brief fixes the runs that use it.
If you cannot say which line of the brief would have prevented it, you have not finished diagnosing.
In this site’s experience, most diagnoses end in one of four edits: a tighter scope, an explicit stopping condition, a required artefact, or the line forbidding action on fetched content. The brief template has all four.