references/debugging-runbooks.md

# Fault isolation for tool-using agents
Triage from real evidence: expected/actual outcomes, versions, trace run ID, tool calls and external state, followed by a minimal reproduction. Classify defects at input parsing, context retrieval, planning/routing, tool schema, authorization, provider failure, state persistence, prompt injection, evaluation or UX layer.

Start with the first divergence, not the final response. Typical cases: duplicate write after timeout; manager prematurely concludes; tool returns an HTML error; handoff drops user context; stale memory overrides current authoritative data; tool invocation loops; structured output fails schema. Write a regression test that fails before the fix when possible, change the smallest component, rerun tests and compare baseline. Never claim production incident resolution from trace snippets alone.