How to Write an Incident Post-Mortem (With AI Templates)

Why Post-Mortems Are Consistently Skipped

The post-mortem is the single highest-leverage activity in incident response. It converts a painful, costly incident into organizational learning that prevents the next one. And yet, in most engineering organizations, fewer than 30% of significant incidents have an associated post-mortem — and of those that are written, fewer than 50% result in action items that are actually completed.

The reasons post-mortems get skipped are predictable: teams are exhausted after resolving an incident, the next sprint starts immediately, there's social discomfort in analyzing mistakes, and writing a thorough post-mortem feels like it takes more time than the incident itself. These are real constraints, not discipline failures. The solution is not to demand more discipline — it's to reduce the activation energy of the process.

AI-generated post-mortem drafts solve the activation energy problem. When the draft is generated automatically from incident timeline data and log analysis, the engineer's job changes from 'write a document' to 'review and improve a draft.' This 80% reduction in writing effort means post-mortems get done — and done well.

Blameless Culture: The Non-Negotiable Foundation

A blameless post-mortem does not ask 'who did this?' It asks 'what conditions made this possible?' This distinction is not just cultural kindness — it's epistemically correct. Complex systems fail because of systemic conditions, not because individuals made poor decisions. The engineer who deployed the change that caused the outage made the best decision they could with the information and tooling available to them at the time.

If your post-mortem process leads to engineers being held personally responsible for incidents, you will get one of two outcomes: engineers who avoid deploys (slowing down your engineering velocity) or engineers who hide incidents (making your system invisibly fragile). Neither is acceptable. Blame is not just unkind — it actively destroys the safety culture that makes honest, thorough post-mortems possible.

Blameless does not mean consequence-free for systemic negligence. If an engineer skipped a code review, bypassed a mandatory process, or ignored a prior warning, that is worth noting as a contributing factor. The frame is 'what did this reveal about our process?' not 'who was negligent?'

The Anatomy of a Useful Post-Mortem

A post-mortem that produces organizational learning has eight components. Not all eight need to be comprehensive for every incident — a minor incident might have a 200-word post-mortem, a major one might run 2,000 words — but all eight should be present.

• Incident title and severity: Brief description and impact classification (P1–P4, SEV1–SEV4, etc.)
• Summary: 2–3 sentences. What broke, how long, what was the impact on users?
• Timeline: Chronological record of events — when it started, when it was detected, key investigation steps, resolution. Times in UTC.
• Root cause: The specific technical cause. Not 'human error' — that is never the root cause.
• Contributing factors: The conditions that made the root cause possible. Usually 3–6 items.
• Impact: Quantified. Duration x affected users x estimated revenue impact.
• Action items: Each item has an owner, a due date, and a priority. Without owners and dates, they won't happen.
• Lessons learned: What would have made this faster to detect, investigate, or resolve?

An AI-Generated Post-Mortem: Annotated Example

The following is an example of what ObservabilityOS generates automatically from incident timeline data within 5 minutes of incident resolution. The engineer's review time is typically 10–15 minutes to verify accuracy, add nuance, and assign action item owners.

# Incident Post-Mortem: Checkout Service Outage
**Date:** 2026-07-05 | **Severity:** P1 | **Duration:** 23 minutes
**Author:** AI-generated draft — reviewed by @alex.chen

## Summary
The checkout service returned HTTP 500 errors for 23 minutes from 03:47 to
04:10 UTC due to MongoDB connection pool exhaustion triggered by a deploy
that introduced N+1 queries on the product loading path.

## Timeline (UTC)
03:35 — Deploy v2.4.2 deployed to checkout-api (3 instances)
03:47 — Error rate anomaly detected (Z-score: 4.8) → incident opened
03:49 — On-call engineer paged. AI RCA card generated.
03:52 — Engineer identifies root cause from AI card (N+1 query pattern)
04:02 — Rollback to v2.4.1 initiated
04:10 — Error rate returns to baseline. Incident resolved.

## Root Cause
Deploy v2.4.2 added eager loading of related products, executing one
MongoDB query per cart item instead of a single aggregation. A cart with
12 items triggered 12 concurrent queries, exhausting the connection pool
(max: 10 connections) 12 minutes after deployment as traffic ramped up.

## Contributing Factors
- Connection pool max (10) was not documented or reviewed during code review
- No load test was run against the eager loading implementation
- The deployment monitoring window (5 min) was too short to catch gradual exhaustion

## Impact
- 23 minutes of checkout unavailability
- ~340 failed checkout attempts (estimated)
- ~$17,000 in potentially lost GMV (estimated at $50 average cart)
- 0 customer SLA violations (SLA threshold: 99.5% monthly availability)

## Action Items
| Action | Owner | Due | Priority |
|--------|-------|-----|----------|
| Add connection pool config to code review checklist | @marcus.reid | Jul 12 | P1 |
| Implement query count assertions in CI for N+1 detection | @priya.sharma | Jul 19 | P1 |
| Extend deployment monitoring window to 15 minutes | @alex.chen | Jul 12 | P2 |
| Document MongoDB connection pool sizing guidelines | @priya.sharma | Jul 26 | P2 |

Storing and Acting on Post-Mortems

A post-mortem that lives only in a Google Doc is a post-mortem that will not drive change. Post-mortems should be stored in a searchable, version-controlled system (your team's wiki, Notion, or a dedicated tool), linked from the incident ticket, and tagged by the categories of their contributing factors (e.g., 'deployment', 'database', 'third-party API').

The action items are the most important artifact. Each action item must be entered into your project management system (Jira, Linear, GitHub Issues) with a real owner and a real due date — not just written in the post-mortem document. Schedule a monthly post-mortem review meeting where action items from the previous month are checked. An action item that is never reviewed is not an action item; it's a good intention.

ObservabilityOS maintains a searchable runbook library that is automatically updated when post-mortems are completed. When a new incident resembles a previous one, the relevant post-mortem and runbook are surfaced automatically in the AI incident card. This creates a compounding organizational memory that makes your team more effective with every incident.