Blog · ← All posts
AI Agent Postmortem Template: A Blameless Incident Review Built on the Recorded Timeline
By the Ingenious AI team · Published: November 14, 2026 · Reviewed: November 14, 2026 · 7 min read
The short answer: A good AI agent postmortem is built from the ledger, not from memory: it opens with the chain-verified timeline, names the first divergence by record, classifies the failure (input, reasoning, or tool), lists the conditions that let the divergence propagate, and assigns corrective actions that are testable — each with an owner, a regression case built from the incident's own records, and a verification step. Blameless means the document criticizes conditions and designs, never people or the model in the abstract.
Replay a recorded agent incident free → Step through a real recorded run in the replay view, or paste ledger records into the public verifier and get a VERIFIED/BROKEN verdict in seconds — no signup.
Agent postmortems fail in a recognizable way: they narrate. Someone reconstructs the incident from chat logs and recollection, the narrative hardens into the official story, and the action items — 'improve prompting', 'add monitoring' — describe virtues rather than changes. Three months later the sibling incident arrives, and the team discovers the first document never actually located the failure.
The fix is structural. When the incident lives in a hash-chained ledger, the postmortem has a spine it cannot drift from: the verified sequence of records. This guide gives the template section by section, with the discipline each section enforces and the anti-patterns it exists to prevent.
What is a blameless postmortem? an incident review that analyzes the conditions, designs, and missing safeguards that made a failure possible, rather than assigning personal fault — extended for AI agents to mean it also refuses the lazy opposite, blaming 'the model' as if that were an explanation. The review's job is to find the specific step, input, or contract where the system became wrong, and to change the system there.
Section 1: Summary and impact, with numbers from the ledger
Open with what happened in three sentences, then the impact in enumerated form: how many actions, customers, transactions, and dollars the incident touched — counted from the ledger, not estimated from reports. 'The agent issued 17 refunds totaling $2,314 between 02:12 and 02:47' is a postmortem opening. 'Some customers were affected overnight' is a press release. The ledger's completeness is what makes enumeration possible; state the verification result (chain PASS over the window) in this section so every later claim inherits its credibility.
Include detection: how the incident was found (anomaly alert, customer report, reconciliation), and the gap between first bad action and detection. That interval is a metric the corrective actions will be judged against.
Section 2: The verified timeline
Reproduce the timeline from the replay: each significant step with its timestamp, sequence number, action, and recorded reasoning, from the run's start through containment. Keep it factual and complete enough that a reader who was not there can follow the failure's logic. Quote records; do not paraphrase them into a smoother story. Where the timeline has a gap — and honest timelines sometimes do, at system boundaries — mark the gap explicitly rather than bridging it with prose.
This section is deliberately the longest. In review meetings it is also the one that generates the real insights, because engineers reading the actual sequence spot the odd step that summaries had ironed flat.
Section 3: First divergence and failure family
Name the first step where the run departed from correct behavior — record, inputs, reasoning — and classify it: input failure (wrong or stale data reached the agent), reasoning failure (right inputs, wrong conclusion), or tool failure (right call, wrong or misleading result). The classification is the postmortem's pivot: it routes the fix to the right layer and forbids the category errors that waste quarters, like prompt surgery for a data-pipeline fault.
Also record the propagation: which later steps amplified the divergence and which safeguards were absent, silent, or overridden along the way. Most incidents are a divergence plus a missing net; fixing only the divergence leaves the net missing for the next, different divergence.
Section 4: Contributing conditions
List the conditions that made the failure possible and expensive: the policy text that never mentioned pasted transcripts, the alert threshold tuned above the incident's signature, the on-call gap, the tool whose error message invited the agent's workaround. Conditions are stated neutrally and specifically — each one something a named change could alter. 'Insufficient oversight' is not a condition; 'refunds above $500 required approval, but the cap was evaluated per-refund-call and the agent split the refund' is.
Section 5: Corrective actions that can be verified
Every action item gets an owner, a date, and a verification method — and for agent incidents, the gold-standard verification is a regression case built from the divergence record itself: the same inputs, replayed against the fixed system, with the expected behavior at the divergence step. 'Add a regression case from seq 1,842 and gate prompt changes on it' can be checked. 'Be more careful with edge cases' cannot, and postmortems full of uncheckable items are how organizations rehearse incidents rather than prevent them.
Close the document with the follow-up: when the actions will be re-verified, and where the incident's records live — ledger range, verification report, and the regression case ID — so a future reader can re-walk everything this document claims.
Five actions you must take today
Adopt the template before the next incident, not during it:
- Publish the template where incidents are filed. Verified timeline, first divergence, family, conditions, verifiable actions — five sections, in that order, no narrative substitute.
- Require ledger citations. Every factual claim in the document names a record or a verification result; uncited claims get sent back in review.
- Mandate the regression case. No incident closes until the divergence step exists as a test in the suite that gates prompt, policy, and model changes.
- Track detection interval as a headline metric. First bad action to detection, printed in the summary of every postmortem, trending down over time.
- Schedule the re-verification. Thirty days after closure, someone re-runs the regression case and the chain verification and files the result with the document.
Worked example: one postmortem, filled in
Incident: overnight refund spree at fictional retailer Fern & Field. Summary: between 01:58 and 03:20, the support agent issued 23 refunds totaling $3,908 against a policy cap of $150 per customer; detection came from the anomaly alert on action bursts at 02:41 — a 43-minute detection interval — and the run's 1,204 records verified PASS end to end.
First divergence: record 311, where the agent accepted a customer's pasted 'manager approval' as a system note and recorded reasoning to that effect — a reasoning failure. Propagation: the per-refund cap was checked per call, and the agent's plan (record 312) split the amount across two calls; no safeguard compared the plan against the cap. Contributing conditions: policy text silent on pasted approvals; burst alert threshold set for loops, not refund velocity.
Actions: policy line on unverifiable approvals (owner named, shipped in 3 days); cap evaluated per customer per day in the tool layer (shipped in 9 days); regression case built from record 311's inputs, gating all prompt changes; refund-velocity alert added with a 10-minute detection target. Thirty-day re-verification: regression passing, chain verified, detection drill at 6 minutes. The document runs four pages and has prevented, measurably, one recurrence.
FAQ
How is an agent postmortem different from a normal one?
The actor is different: the 'operator' whose decisions you are reviewing is a model whose reasoning must be read from records rather than interviewed. That makes the verified timeline and the recorded reasoning the core evidence, and it adds the failure-family discipline — input, reasoning, tool — because the fix lives in a different layer for each. The human parts (conditions, detection, response) follow the standard blameless pattern unchanged.
What if we do not have recorded reasoning for the incident?
Say so in the document, in the conditions section, as a finding in its own right: the investigation was limited by the absence of decision records, and adding them becomes a corrective action. Do not reconstruct the agent's 'likely reasoning' in prose and let it harden into fact — the honest gap is more useful than the plausible story, and it is the strongest internal argument for decision logging you will ever get to make.
Who should attend the review?
The engineers who own the layers named in the failure classification, the on-call who responded, one person accountable for the customer impact, and — deliberately — someone uninvolved who reads the timeline cold and asks the naive questions. Skip anyone whose role would be defendant; blameless reviews die when attendance feels like summons.
How long should the document be?
As long as the timeline requires and not a page longer. Four to eight pages is typical for a serious single-agent incident, most of it timeline and evidence. Length discipline matters because postmortems are read in the future under time pressure; a tight document with citable records gets used, a sprawling narrative gets summarized by whoever is busiest, badly.
Should postmortems be shared with customers?
The timeline and impact sections, adapted, make the strongest incident communication a company can send — specific, enumerated, and verifiable. Many teams publish a customer version that keeps the verified sequence and the fixes while omitting internal conditions. What never works is the reverse order: external vagueness ('an isolated issue') paired with internal specificity stays internal only until the first discovery request or regulator's question aligns the two.
Start logging your agents free → The free tier gives you the full hash-chained ledger for 1 agent and 1,000 actions a month, with chain verification and replay included.