Symptom-to-Architecture-Cause Mapping

Symptom-to-architecture-cause mapping is the diagnostic skill of taking a production complaint about an agent and identifying which part of the architecture is responsible — because the fix lives at the cause, not the symptom. Retrying, re-prompting, or adding examples wastes effort when the real defect is structural.

Two mappings recur. When an agent calls the wrong tool or routes to the wrong sub-agent, the cause is almost always a weak or ambiguous tool description — the model chose based on the metadata you gave it, so the fix is clearer tool names, descriptions, and parameter docs, not a bigger model. When an agent is confidently wrong — fluent, assured, and factually off — the cause is usually context: relevant information was dropped, truncated, or summarized away before the model saw it, so it reasoned correctly over missing inputs.

Other pairings follow the same discipline: repeated identical failures point at a deterministic prompt or schema defect; nondeterministic flakiness points at retrieval, ordering, or temperature. The exam-correct move is to name the layer — tool metadata, context assembly, retrieval, permissions — and fix there, rather than treating every symptom as a prompt-tuning problem.