Skip to content

Agent Failure RCA —

Copy this file to docs/agents/rca/<YYYY-MM-DD>-<slug>.md and fill it in before any re-run. Taxonomy and method are taught in Chapter IV — The Oracle Rubric.

Incident

  • Run:
  • Agent / workflow: _data/agents/registry.yml>
  • Task:
  • Failure mode (one sentence):

Layer classification

Pick ONE primary layer (the fix differs entirely by layer):

  • Reasoning / planning — the agent built the wrong thing
  • Tool misuse — a tool was called with bad arguments
  • Permissions — an API refused the token's scope
  • Context drift — the world changed under the plan
  • Environment — a file, secret, or dependency was missing
  • Completion — success declared before the signals said so

Evidence (log lines, diff, trace excerpt):

5-Why

  1. Why did it fail? →
  2. Why? →
  3. Why? →
  4. Why? →
  5. Why? →

Root cause

Prevention (shipped)