Curated reading path
Debugging agent failures
Work backward from an unmet requirement to the tool result, environment, and evidence that led to it.
Begin with what should have happened
For readers who have a completed-looking run and an incorrect result. Keep the task description, changed artifact, and observable tool log together. The goal is to find the first unsupported decision, not simply attach a failure label to the model.
Read in order, checking each concept against that evidence. A successful tool call may be relevant, irrelevant, incomplete, or aimed at the wrong target.
Reading order
- Spec
Establish an observable success criterion independent of the agent’s chosen actions.
- Tool call
Inspect the requested target and arguments; a well-formed request can still be wrong.
- Tool result
Distinguish completion, errors, denials, and partial observations.
- Environment
Check the actual repository, process, or service the tool operated on.
- Contextual knowledge
Find the supplied evidence behind the agent’s decision.
- Hallucination
Recognize unsupported claims without treating every bad action as a hallucination.
- Automated check
Determine what the green checks covered and what they omitted.
- Human review
Compare the artifact and evidence with the original request.
Make one targeted repair
Write the unmet acceptance criterion in one sentence. Identify the earliest call whose result did not justify the next action. Repair the missing evidence, target selection, or check, then repeat the bounded task. If you cannot locate the gap from the trace, improve the tool’s result details before drawing a conclusion about model capability.