Post-Mortem Generator

How to write a blameless post-mortem

After an outage, teams need a shared story: what happened, why, and what changes prevent a repeat. A blameless post-mortem focuses on systems and process — not on finding someone to punish. That honesty is what makes the document useful six months later when memory has faded.

The term comes from aviation and healthcare, where hiding mistakes costs lives. In software, the stakes are usually financial and reputational, but the learning mechanism is the same: if people fear blame, they omit details — and the same failure returns under a new name.

Why post-mortems matter for reliability culture

Incidents are expensive in minutes and dollars. A post-mortem converts that cost into institutional knowledge. Without one, you pay twice: once for the outage and again when the untested fix fails. Pair narrative with numbers from the Error Budget Calculator and Downtime Cost Calculator so leadership sees both SLO burn and revenue impact.

Recommended sections (and what each should answer)

• Summary: One paragraph an executive can read in 30 seconds — what broke, how long, who was affected.
• Impact: Users, regions, revenue estimate, support ticket volume, SLA/error budget consumed.
• Timeline: UTC timestamps from first signal → detection → declaration → mitigation → recovery.
• Root cause: The technical trigger (not “human error” as a stopping point).
• Contributing factors: Missing monitors, unclear runbooks, deployment policy, vendor delay.
• What went well / poorly: Celebrate fast rollback; note confused comms or missing owner.
• Action items: Owned, dated, tracked to completion — fewer strong items beat long wish lists.

Timeline methodology

Build the timeline from logs, pager timestamps, and chat exports — not from memory alone. Include when customers first reported issues if that precedes internal detection (detection lag is its own action item). Note every status page update with UTC time; communication delays erode trust even when engineering recovery is fast.

Worked example — impact paragraph with numbers

Worked example — root cause vs contributing factors

Action items that actually ship

Prefer fewer, concrete actions. Each needs an owner (@handle) and due date. “Improve monitoring” is weak; “Add p95 latency alert on checkout-api > 800ms, owner @sam, due 2026-04-15” is strong. Track items in your ticket system; reopen the post-mortem if items slip twice.

When NOT to write a full post-mortem

• SEV3 with zero customer impact and clear one-line fix — a brief incident note may suffice.
• Active incident still in progress — write timeline notes live, publish post-mortem after stability.
• Legal or law-enforcement sensitive events — coordinate with counsel before publishing internally.

Honest limits of this generator

This tool formats fields into Markdown. It does not interview witnesses, pull logs, or enforce blameless review facilitation. Schedule a meeting for contested incidents; the document is the output, not the whole process.

Facilitation tips for the review meeting

Assign a neutral facilitator not involved in the deploy chain. Time-box root cause discussion to prevent infinite “five whys.” Read the timeline aloud once — participants often discover gaps when hearing UTC sequence spoken. End with explicit owners for each action item read back from the doc.

Customer-facing vs internal post-mortem

Public summaries should acknowledge impact, apologize without over-promising, state remediation themes, and omit employee names, security details, and vendor contract disputes. Internal docs can include graph screenshots, exact ticket counts, and candid process failures. Generate internal Markdown here; write customer copy separately with comms/legal review.

Metrics to attach when available

• MTTD (mean time to detect) and MTTR (mean time to recover)
• Error budget burn % for the period
• Estimated revenue or pipeline impact with calculator link
• Support ticket volume vs baseline
• Failed deployment or change ticket ID

Deep dive: five whys without blame theater

“Five whys” still works when each why points to a controllable system change. Stop when you reach human error without a process fix — then ask why the process allowed the error (missing review, bad default, alert fatigue). The generator’s root cause field should hold the technical trigger; contributing factors hold the organizational layers.

Store post-mortems in a searchable wiki tagged by service and failure mode. Before changing architecture, search “database failover” — you may find the same lesson paid for twice. Link post-mortems from error budget reviews when burn spikes so patterns surface quarterly, not only during SEV1 adrenaline.

New hires should read the last three post-mortems for their service in week one. That onboarding habit beats abstract reliability training slides.

Review meeting agenda (60 minutes)

1. 5 min — facilitator reads summary
2. 15 min — timeline walk UTC
3. 15 min — root cause and contributing factors (no blame)
4. 10 min — what went well / poorly
5. 15 min — action items with owners; no new scope without ticket

Record decisions in the generated Markdown; assign scribe separate from facilitator.

SEV classification methodology (when to post-mortem)

Level	Typical trigger	Post-mortem?
SEV1	Core revenue path down for most users	Required within 5 business days
SEV2	Major feature impaired, workaround exists	Required
SEV3	Minor impact, fast fix	Optional brief note
Near-miss	Would have been SEV1 if timing differed	Recommended — cheap learning

Duration alone does not set severity: 25 minutes of total checkout loss may be SEV1; 3 hours of delayed internal reports may be SEV3. Document the severity rationale in the generated doc header.

Common mistakes in post-mortems

• Stopping at “human error.” Without process fix, next human repeats it.
• Timeline from memory on day 3. Logs disagree — build from exports first.
• Action item laundry list. 22 items ship zero; pick 3–5 with owners.
• Missing detection lag. Customer tweets preceded pager by 20 minutes — that is a metric (MTTD).
• Public doc with security details. Rotate credentials mentioned in internal version only.
• No follow-up review. Re-open if action items slip two sprints — doc becomes fiction.

Worked example — full incident with MTTD/MTTR numbers

Honest limits

Browser-only Markdown formatter — no log ingestion, no automatic timeline from PagerDuty, no blameless facilitation. The review meeting and evidence gathering are the work; this tool standardizes output structure so teams spend time on learning, not formatting.

Related tools

Customer comms: Status Page Builder · Vendor credit: SLA Credit Claim Pack · Money math: Reliability Money Toolkit · Free Tools.