Turn an incident into a blameless postmortem. Fill the form, get ready-to-file Markdown.
The generator output is meant to be pasted into a ticket, pull request, or design review. It should name the owner, decision, evidence, and follow-up work before implementation starts.
Incident: duplicate refund attempt Spec gap: - retry behavior was not defined - support UI ignored pending provider state Follow-up: - add idempotency acceptance criteria - add provider-timeout fixture
Treat the generated postmortem draft as a starting artifact. Replace example values, attach evidence, assign reviewers, and remove sections your team will not maintain.
A good postmortem is blameless, mechanistic, and actionable. Blameless: no individual is at fault; the system is. Mechanistic: explain how the failure propagated, not just "X broke". Actionable: every finding has an owner, a due date, and lives in a tracker you actually check.
Related reading: Postmortem: Breaking API Change Without Contract Tests and the Edge Case Checklist.
Use the summary and timeline for observable facts: timestamps, alerts, deploys, customer impact, and mitigation steps. Put analysis in root cause, contributing factors, and lessons learned so readers can audit the reasoning.
Describe affected users, failed requests, revenue impact, data risk, SLO burn, support load, and duration. If a number is estimated, label it as an estimate and explain how it was derived.
A good root cause explains how a system failed, not who made a mistake. Write the chain: trigger, missing guardrail, propagation path, detection gap, and why the existing process did not stop it.
Every action item should have an owner, due date, tracking location, and verification method. "Improve monitoring" is not enough; "alert when checkout 5xx exceeds 2% for 5 minutes" is reviewable.
Did the team learn about the incident from its own monitoring, from users, or from downstream effects? What signal should fire earlier next time?
Was there a known rollback path, runbook, feature flag, or circuit breaker? If not, the action item should improve response speed, not just prevention.
Which spec, test, migration check, contract gate, or review question would have caught this before release?
Improve deploy checks and add better alerts.
This is too broad to assign, verify, or close. It does not say which check, which alert, what threshold, or what outcome prevents recurrence.
Add a migration gate that blocks NOT NULL column additions without default or backfill plan. Owner: database platform. Due: 2026-05-15. Verification: failing fixture migration in CI.
This action item is specific, owned, dated, and testable.
Use the draft to verify facts with incident responders, support, product, and engineering. The meeting should correct the timeline, confirm impact numbers, and remove speculation that is not backed by logs or customer evidence.
A postmortem document is not a task system. Copy each follow-up into the team tracker with owner, due date, verification method, and a link back to the incident so completion can be audited later.
Schedule a follow-up check for the due dates. If an action item was closed without evidence, reopen it or replace it with a smaller, testable fix that still reduces recurrence or detection time.
A reader should understand what failed, who was affected, how the team detected it, how mitigation worked, and which evidence supports the root cause without needing private chat history.
Every action item should have a tracker link, owner, due date, and verification method so the team can check whether it was completed and whether it actually reduced recurrence or detection time.
Use the generated timeline for timestamped facts, then keep causal analysis in the root-cause section. This prevents the review from mixing what happened, why it happened, and what the team will change next.
The Markdown is not the system of record for follow-up. Copy each action item into your issue tracker with owner, due date, verification method, and a link back to the postmortem so it does not disappear after the meeting.
Start the draft while facts are fresh, but do not close it until logs, customer impact, timeline, and follow-up owners are verified. A rushed postmortem often creates vague action items.
Usually two to five. More than that often means the team is listing every possible improvement instead of choosing the few changes that would most reduce recurrence or shorten detection.
The form separates timeline, impact, detection, response, root cause, lessons, and action items so reviews do not collapse facts, interpretation, and follow-up work into one vague incident note.
Generated postmortems are judged by whether they identify a mechanism of failure, name detection and mitigation gaps, and produce action items with owners, due dates, and verification methods.
Author and editor: Daniel Marsh. Review process: Editorial Policy. Corrections and tool issues: Contact. Last reviewed: April 28, 2026.