A Blameless Incident Postmortem Template With a Worked Example

An outage you do not learn from is an outage you will repeat. A good postmortem turns a stressful afternoon into a short document that explains what happened, why the system allowed it and what will change. This guide covers the principles, the structure and the pitfalls, and gives you a complete template and a filled-in example you can adapt for a small business.

When to write one

Not every blip needs a document. Write a postmortem when:

• Customers were visibly affected for more than a few minutes.
• Data was lost or at risk.
• You had to take emergency action, such as a rollback or manual failover.
• You were lucky: it could easily have been worse.
• You found out from a customer rather than from your own monitoring.

Short incidents can use a shorter form of three paragraphs: what happened, why, what changes. The point is the learning, not the paperwork. The incident postmortem generator can produce a first-draft structure from your notes.

Blameless means asking better questions

"Blameless" does not mean "nobody is accountable." It means that you treat human error as a symptom of a system that made the error easy, not as the cause to be punished.

• Replace "Who ran the command?" with "Why was it possible to run that command against production without a confirmation?"
• Replace "Why didn't Sam notice?" with "What would have made this visible to anyone on call?"
• Assume everyone involved made reasonable decisions with the information they had at the time.

If people expect to be blamed, they will hide details, and you lose exactly the information the postmortem needs. In a two-person company, the same applies: write as if the person involved were a colleague you respect, even if it was you.

The timeline

The timeline is the backbone. Build it before writing any analysis.

1. Collect sources. Monitoring alerts, chat logs, deploy history, server logs, provider status pages, and the customer messages that came in.
2. Use one time zone. UTC, stated explicitly, avoids confusion across systems.
3. Record facts, not interpretations. "14:02 Monitor reported checkout failing" is a fact. "14:02 The database crashed" is an interpretation unless you know it.
4. Include the decisions. Note what people tried and why, including the things that did not work. Dead ends are useful.
5. Mark the key moments: start of impact, detection, first response, mitigation, resolution.

From the timeline you can compute the numbers that matter most:

• Time to detect: impact start to first alert or report.
• Time to mitigate: detection to customers no longer affected.
• Total duration of impact.

A long time to detect points at monitoring gaps; see how often should you monitor a website. A long time to mitigate points at runbooks, access or rollback ability.

Root cause, trigger and contributing factors

Incidents rarely have a single cause. Separate three ideas:

• Trigger: the event that started the incident, such as a deploy, a traffic spike or a certificate expiring.
• Root cause (or causes): the underlying conditions that turned the trigger into an outage, such as no disk-space alert.
• Contributing factors: things that made it worse or longer, such as unclear ownership or a slow rollback process.

A deploy is often the trigger, but it is rarely the root cause. If a single deploy can take the site down, the weakness is the absence of tests, canaries or quick rollback, and those are what to fix.

5 whys, and where it falls short

The 5 whys technique asks "why?" repeatedly until you reach a fundamental cause. Example:

1. Why was the shop down? The database stopped accepting writes.
2. Why? The disk was full.
3. Why? Log files grew without limit.
4. Why? Log rotation was not configured on the new server.
5. Why? The server was set up by hand without a checklist.

It is a good prompt for thinking and takes minutes. But be aware of its limits:

• It follows one chain and ignores others. Here, "why was there no alert for disk usage?" is a separate and equally important chain.
• Stopping at "human error" is a failure of the technique, not an answer.
• The number five is arbitrary. Stop when the answer is something you can change.
• Different people produce different chains from the same incident. Treat the result as a hypothesis, not a proof.

A fishbone diagram or simple lists under "what went well", "what went badly" and "where we got lucky" complement it well.

Action items that actually get done

Most postmortems fail at this step. Each action item needs:

Prefer fewer, stronger actions. Three completed items beat fifteen forgotten ones. Classify them:

• Prevent: stop this from happening again, such as log rotation.
• Detect: notice sooner, such as a disk alert.
• Mitigate: reduce impact, such as a tested rollback.

Review them a week or two later. If an action is not worth doing, say so and close it deliberately.

Sharing it

Publish the postmortem internally at least. For customer-visible incidents, a shortened version, with cause, impact, duration and what you are changing, builds trust. Link it from the resolved update on your status page, as described in the status page guide. Leave out credentials, internal addresses and personal blame.

Copy-paste template

# Postmortem: <short title>

Date of incident: <YYYY-MM-DD>
Authors: <names>
Status: Draft | In review | Final
Severity: <e.g. Sev 2: major feature unavailable>

## Summary
Two or three sentences: what broke, who was affected, how long, how it
was fixed.

## Impact
- Duration of customer impact: <N> minutes (<start> to <end> UTC)
- Who was affected: <customers, internal staff, percentage if known>
- Business impact: <orders lost, tickets raised, data affected>

## Detection
How did we find out? (monitor, customer, staff). Time to detect: <N> min.
What could have told us sooner?

## Timeline (all times UTC)
- HH:MM  <event, fact only>
- HH:MM  <event>
- HH:MM  Impact begins / detected / mitigated / resolved

## Trigger
The event that started the incident.

## Root cause(s)
The underlying conditions that allowed the trigger to cause an outage.

## Contributing factors
Things that made it worse or slower to fix.

## 5 whys (optional)
1. Why ...?
2. Why ...?

## What went well
-

## What went badly
-

## Where we got lucky
-

## Action items
| Action | Type | Owner | Due | Ticket |
|---|---|---|---|---|
| <specific action> | Prevent/Detect/Mitigate | <name> | <date> | <link> |

## Lessons and notes
Anything else worth remembering.

Worked example: a small shop's checkout outage

This is a fictional example. The business, "Hollis & Pine," is a small online shop with a developer working part-time.

# Postmortem: Checkout unavailable after database disk filled

Date of incident: 2026-09-12
Authors: Priya (developer), Marcus (owner)
Status: Final
Severity: Sev 2: checkout unavailable, browsing working

## Summary
On Saturday 12 September the shop's checkout stopped working for 52
minutes because the database server ran out of disk space. Product pages
stayed up, but no orders could be placed. We restored service by clearing
old logs and restarting the database, and have since added log rotation
and disk alerts.

## Impact
- Duration of customer impact: 52 minutes (10:41 to 11:33 UTC)
- Who was affected: all customers attempting to check out (14 failed
  attempts recorded in the payment log)
- Business impact: an estimated handful of lost orders; 6 support emails

## Detection
Detected by a customer email at 11:02 UTC, 21 minutes after impact began.
Our uptime monitor only checked the homepage, which kept returning 200.
Time to detect: 21 min.

## Timeline (all times UTC)
- 10:41  Database stops accepting writes (disk 100% full, from logs)
- 10:41  Checkout begins returning HTTP 500
- 11:02  Customer emails support: "payment page gives an error"
- 11:09  Marcus pages Priya by phone
- 11:15  Priya confirms checkout error in application log
- 11:21  Priya identifies "No space left on device" in database log
- 11:24  Status page updated: investigating
- 11:28  Old log files deleted, freeing 9 GB
- 11:31  Database restarted
- 11:33  Test order succeeds; status page set to monitoring
- 12:05  Status page resolved after no further errors

## Trigger
Database general query logging was left enabled after debugging in
August, producing about 4 GB of logs per day.

## Root cause(s)
1. No log rotation or size cap on the new database server.
2. No disk space alert on any server.
3. Monitoring covered only the homepage, not the checkout path.

## Contributing factors
- Marcus did not have Priya's phone on the emergency contact page; it took
  7 minutes to reach her.
- No runbook for "checkout down", so the first 15 minutes of diagnosis
  were improvised.
- The server was built by hand without a setup checklist.

## 5 whys
1. Why did checkout fail? The database could not write.
2. Why? The disk was full.
3. Why? Query logs grew to 40 GB.
4. Why? Debug logging was never turned off and had no rotation.
5. Why? New servers are configured manually with no checklist.
(Separate chain: why did we not know? Monitoring only covered the homepage.)

## What went well
- Priya found the cause within 10 minutes of being reached.
- The fix was safe: only logs were deleted.

## What went badly
- Customers told us before our monitoring did.
- Contact details for the on-call developer were hard to find.

## Where we got lucky
- It happened on a Saturday morning, not during a sale.

## Action items
| Action | Type | Owner | Due | Ticket |
|---|---|---|---|---|
| Disable general query log; configure logrotate and size cap | Prevent | Priya | 2026-09-14 | HP-41 |
| Alert at 80% disk on all servers | Detect | Priya | 2026-09-16 | HP-42 |
| Add keyword monitor for checkout page and payment API | Detect | Priya | 2026-09-15 | HP-43 |
| Write "checkout down" runbook with contact numbers | Mitigate | Marcus | 2026-09-20 | HP-44 |
| Create server setup checklist | Prevent | Priya | 2026-09-30 | HP-45 |

Notice how little blame there is, how the action items map to each cause, and how a separate chain of questions was added to cover detection.

अगले कदम

• Draft one quickly with the incident postmortem generator.
• Narrow down causes with the outage root cause finder.
• Close detection gaps using the uptime monitor and the small business monitoring guide.
• Tell customers what happened with a status page.

सामान्य प्रश्न

What is the difference between a postmortem and a root cause analysis?

A root cause analysis focuses on finding why something failed. A postmortem is broader: it includes the timeline, impact, detection, response quality, root causes and the follow-up actions. The root cause analysis is one section of it.

How long should a postmortem be?

As long as needed and no longer. For a small business, one to two pages usually suffices. If a postmortem is hard to read, its action items will not get done.

Should we publish postmortems to customers?

For incidents that visibly affected them, a shorter public version is usually worthwhile: what happened, how long, what you are changing. Omit internal details, security-sensitive information and names.

What if the root cause is a person's mistake?

Look one level deeper. Ask what made the mistake easy and what would have caught it: a missing confirmation, no review step, unclear documentation, or too little testing. Fix those, and the same mistake becomes much harder for anyone.

How soon after an incident should we write it?

Start the timeline immediately, while logs and chat history are available, and hold the review within a week. Details fade quickly and some logs rotate away.

यह पेज सामान्य जानकारी है, जिसे हमारी संपादकीय टीम ने लिखा है और दस्तावेज़ीकरण बदलने पर अपडेट किया जाता है। सर्वर और प्रदाता अलग-अलग होते हैं, इसलिए बदलाव पहले सुरक्षित तरीके से जाँचें। देखें: संपादकीय नीति और अस्वीकरण.