Anatomy of an agent incident postmortem (with template)
July 12, 2026 · the looptail team
Your agent did something bad — promised an impossible refund, leaked a canned apology to the wrong customer, looped on a tool until a bill arrived. The incident channel is on fire. What separates a two-hour postmortem from a two-week archaeology dig is entirely decided before the incident: whether the decisions were recorded.
The template
Copy this into your incident doc. Sections in bold are the ones LLM incidents add.
- 1. Impact. Who was affected, how many decisions, over what window. (Countable only if decisions are recorded — "we estimate" is the archaeology-dig tell.)
- 2. Timeline. Detection → mitigation → root cause → verified fix, with record ids at each step.
- 3. The decision record. The exact inputs, retrieved context, tool calls, and outputs for representative failures — quoted from the trail, not reconstructed from memory.
- 4. Why the system judged it acceptable. What did evaluation say at the time? Passing (your rubric has a gap), failing-but-unmonitored (your alerting has a gap), or unevaluated (your coverage has a gap). This section names which.
- 5. The introducing change. Which prompt/model/routing change introduced the behavior, when it shipped, what its replay gate said. If you cannot answer this, say so — that is a finding about your change control, and under the EU AI Act's change-control expectations it is the finding that matters.
- 6. Fix and verification. The failing cases added to the regression set; replay results for the fix; canary scores; promotion record.
- 7. Evidence pack. One exported, self-verifying archive of sections 3–6 attached to the doc — for the customer, the auditor, or future-you.
The uncomfortable audit
Run the template against your last incident. Most teams find sections 3–5 were reconstructed from tracing tools with partial retention, a Git history that says "tweak prompt", and Slack. That's not a people failure — it's what happens when the record is an operator convenience instead of a first-class artifact. The fix is structural: per-decision records, append-only andsigned, linked to evaluations and changes, exportable as evidence. Set it up on a quiet Tuesday (it takes ten minutes), and the next fire drill is section-by-section fill-in instead of archaeology.
FAQ
How is an LLM incident postmortem different from a normal one?
The mechanism of failure is a judgment, not a stack trace. You must reconstruct what the system saw (inputs, retrieved context, tool results), what it decided, how that decision was scored at the time, and which change introduced the behavior — which requires per-decision records that most logging setups do not keep.
What should be recorded before an incident ever happens?
Every decision with its inputs, context, output, and outcome signals; every evaluation verdict; every change with its motivation and approval — append-only and signed, so the reconstruction is credible. If the record can be edited after the fact, the postmortem inherits that doubt.
What does “resolved” mean for an agent incident?
The failing cases join the regression set, the fix replays clean against them plus the prior set, the canary holds under live scoring, and the whole sequence — detection to verified fix — exists as a linked chain of records. “We think it stopped” is not resolution.
Who is the postmortem for?
Three audiences: your team (so the fix survives staff turnover), your customers and their security reviews (increasingly asking for AI incident processes), and — for Annex III systems — the EU AI Act’s post-market monitoring and serious-incident reporting expectations.