Postmortem · Incident review · Operations
How to write a postmortem: a blameless guide with a full example
By T. Krause
A postmortem is the written record of an incident and what the team will change because of it. Here is when to hold one, the sections it needs, how to build the timeline and find the causes, and a complete blameless example for a webshop that charged customers twice.
A postmortem is the write-up a team does after an incident. It records what happened, who it affected, how the team fixed it, why it happened and what will stop it happening again. It is also spelt post-mortem, and some teams call it an incident review. A blameless postmortem looks at how the system let the failure through. It doesn't look for the person who pressed the button.
To write one, start within a few days, while people still remember. Build a timeline from logs, chat messages and tickets. Put the impact in numbers. Ask why each event happened until you reach things the team can change, and write down every contributing factor instead of one culprit. Turn each factor into an action with an owner and a date. Then review the draft in a short meeting with the people involved, and keep checking the actions until every one is done.
The rest of this guide goes through each of those steps, then shows a complete postmortem for an invented webshop. If you'd rather start from a page that already has the headings, our post-mortem template has them in place.
When to hold a postmortem
Decide which incidents get a postmortem before you have one. Otherwise the decision gets made by whoever is most tired on the day, and the answer is usually "this one doesn't need it".
Google's Site Reliability Engineering book lists common triggers in its chapter on postmortem culture:
- User-visible downtime or degradation beyond a certain threshold
- Data loss of any kind
- On-call engineer intervention (release rollback, rerouting of traffic, etc.)
- A resolution time above some threshold
- A monitoring failure (which usually implies manual incident discovery)
The same chapter says "it is important to define postmortem criteria before an incident occurs so that everyone knows when a postmortem is necessary", and that "any stakeholder may request a postmortem for an event".
The list comes from running software at Google's scale, but the idea carries over to a small team. Pick your own thresholds and write them on one page. A shop might say: any incident customers noticed, any incident that cost money, anything that needed a rollback and anything we found out about from a customer instead of an alert. Teams outside engineering can use the same format for a missed deadline or a launch that went wrong.
Near misses count too. If a deploy almost wiped the customer table and someone caught it at the last second, the postmortem costs an hour and the lesson is free.
What blameless means in practice
The SRE book puts it this way: "For a postmortem to be truly blameless, it must focus on identifying the contributing causes of the incident without indicting any individual or team for bad or inappropriate behavior. A blamelessly written postmortem assumes that everyone involved in an incident had good intentions and did the right thing with the information they had."
The reason is practical. If the last person who made a mistake got named and shamed in the write-up, the next person keeps quiet, and you lose the facts you need. A few habits make blameless real instead of a line at the top of the page:
- Describe decisions with the information people had at the time. "The on-call engineer saw a normal error rate on the dashboard and closed the alert" is a fact. "The on-call engineer ignored the alert" is a verdict.
- Never stop at "human error". A person typing the wrong value is where the investigation starts. The questions are why the system accepted the value and why nothing caught it.
- Ask "what" and "how" instead of "why did you". "What did you see when you opened the dashboard?" gets an answer. "Why didn't you check the queue?" gets a defence.
- Use roles in the causes section. Names in the timeline help readers follow events. In the causes, "the deploy" or "the on-call engineer" keeps the focus on the system.
Blameless doesn't mean nobody is responsible for anything. Every action at the end has a named owner. The difference is that people are responsible for the fixes, not punished for the failure.
The sections of a postmortem
Start with a title that says what broke, not the date or a ticket number. "Customers charged twice during a payment timeout" gets found by the next person with the same problem. Under the title, put one line with the date of the incident, the author, the status (draft, reviewed, actions done) and a severity if your team uses levels. Then come six sections:
- Summary. Three or four sentences that someone outside the team can read on their own. What happened, how long it lasted, who it affected and whether it is fixed.
- Impact. The damage in numbers. Customers affected, money involved, support tickets, minutes of downtime, data lost or not lost. If you don't know a number, write that you don't know it.
- Timeline. Times and events in order, from the first sign of trouble to the end of the clean-up. Use one time zone and say which.
- Root cause and contributing factors. Why it happened. Incidents often have several causes that only did damage together, so list each one.
- What went well and what didn't. What helped the team recover, which you want to keep, and what slowed it down.
- Actions. Each change you will make, with one owner and a due date. Mark the ones already done.
A small incident can get by with a few lines per section. Keep all six headings anyway. The empty one is often the one nobody thought about.
How to build the timeline
Write the timeline first, before anyone argues about causes. It is the part people remember worst, and every other section depends on it.
Collect the raw material in one place. That means alerts and their timestamps, deploy logs, the chat channel where people talked during the incident, support tickets and any status page your suppliers run. Then write one line per event, with the time first:
- Write what happened, not what it meant. "12:05 Rosa posts the third duplicate-charge email in the support channel" instead of "12:05 Support finally escalates".
- Include when people found out, not only when things broke. The gap between the start of the problem and the first person knowing is often the most useful number in the whole document.
- Mark guesses as guesses. "About 11:00 (provider status page)" is fine. A precise time you made up isn't.
- Stop when the clean-up is finished, not when the system came back. Refunds, customer emails and data repair belong in the timeline.
Ask everyone involved to read the timeline and correct it before you move on. People who were there will spot the step you missed.
How to find the causes
A simple method is to ask "why" over and over, often five times, which is where the name "five whys" comes from. Take the visible failure and ask why it happened. Take the answer and ask why again. Stop when you reach something the team can change.
For the webshop in the example below, a first chain looks like this:
- Why were customers charged twice? Because they clicked Pay a second time and both payments went through.
- Why did they click again? Because the checkout showed "Payment failed, please try again".
- Why did it say the payment failed? Because the payment provider took longer than 10 seconds to answer, and the checkout treated a slow answer as a failure.
- Why did the second click create a second charge? Because the checkout sent each click as a new payment request, with nothing that let the provider recognise a repeat.
- Why did it take an hour to page anyone? Because nothing alerted on payment errors, so the shop found out from customer emails.
The method has limits, and knowing them makes it more useful:
- It follows one chain. Incidents often have several causes. Run the questions again from each branch, as the example does at steps 4 and 5.
- It can stop at a person. "Why? Because Ana set the timeout to 10 seconds" is a dead end. Ask why 10 seconds looked right when she set it, and why nothing tested it against a slow provider.
- The number five means nothing. Stop when the answer is something you can act on. Sometimes that's after three questions, sometimes after seven.
- Different people get different answers. Do it together in the review meeting, not alone at a desk.
The result goes in the root cause section as a short paragraph followed by the contributing factors as a list. Each factor should lead to at least one action.
The review meeting
The author writes the draft, then the team reviews it together. Plan thirty to sixty minutes. Invite the people who handled the incident, the person who will own most of the actions and someone from any team the incident touched, such as support. Keep it small enough that everyone talks.
Share the draft a day before and ask people to comment on it, so the meeting is spent on the parts people disagree about. A workable agenda:
- Read the summary and impact aloud and check everyone agrees with the numbers.
- Walk through the timeline and fix anything wrong.
- Go through the causes together, asking why for each one.
- Agree on the actions, one owner and one date each.
- Decide who sends the finished postmortem to whom.
The person running the meeting watches the language. When someone says "if only Ana had checked", they bring it back to what the system could have done. If the review leads to a bigger decision, such as changing payment provider, record it in a decision log with the reasons, so the next team knows why.
Following up the actions
A postmortem with open actions is still an open incident. Most of the value sits in the actions, and they are the part that gets dropped once the urgency is gone.
- Move each action into the place where the team plans its work. If actions only exist inside the postmortem, nobody looks at them during sprint planning.
- Keep the owner and date in the postmortem too, and tick each action off there when it's done.
- Check open actions at a fixed time, for example at the weekly team meeting, until the list is empty.
- Change the status to "actions done" at the end, and send a two-line note to everyone who read the first version.
If an action keeps slipping, say so in the postmortem. "Moved to November, the alert needs the new monitoring setup first" is more honest than a date that quietly passed.
A filled-in example: customers charged twice
The shop, the people and every number below are invented. It is a small online shop that sells bicycle parts, with a team of five. Ana is the developer and was on call that weekend. Malik looks after hosting and monitoring. Rosa runs customer support. Tobias is the founder and approves refunds.
Postmortem: customers charged twice during a payment timeout
Incident date: Saturday 3 October 2026. Author: Ana Reyes. Reviewed: 6 October 2026, with Malik, Rosa and Tobias. Status: reviewed, actions open. Times: CEST.
This postmortem is blameless. We look at how the checkout let this happen, not at who did what.
Summary
On Saturday 3 October, our payment provider answered slowly for about two hours. Our checkout gave up after 10 seconds and told customers the payment had failed, even when it had gone through. 200 customers paid again and were charged twice. We closed the checkout for 54 minutes, refunded every duplicate charge by Monday afternoon and emailed each affected customer.
Impact
- 200 customers charged twice, €9,860 in duplicate charges, all refunded by 5 October at 14:00
- Checkout closed from 12:31 to 13:25 (54 minutes). We don't know how many orders we lost in that time.
- 64 support emails over the weekend and on Monday
- No orders lost or shipped twice. Each customer got one order and one refund.
Timeline
- 11:00 (about, from the provider's status page) The payment provider's response times start to rise.
- 11:04 First checkout timeout. The checkout shows "Payment failed, please try again". The provider completes the payment a few seconds later.
- 11:04 to 12:31 Customers who see the message click Pay again. Each click sends a new payment request.
- 11:41 First support email: "I've been charged twice."
- 12:05 Rosa gets the third email with the same complaint and posts in the incident channel. Ana is paged.
- 12:18 Ana finds pairs of charges a minute apart in the provider dashboard and matches them to checkout timeouts in our logs.
- 12:31 Ana closes the checkout and turns on the maintenance banner.
- 13:10 The provider's status page reports that response times are back to normal.
- 13:25 Ana places three test orders, all succeed, and she reopens the checkout.
- Monday 5 October, 09:30 Malik runs a query that lists every customer with two charges for one order. It finds 200.
- Monday 5 October, 14:00 Tobias approves the refunds, Rosa issues them and sends each customer an apology with the refund confirmation.
Root cause and contributing factors
The checkout treated a slow answer from the payment provider as a failed payment. It told customers to try again and sent their second click as a brand new payment, so the provider charged them twice. Four things had to line up:
- The checkout waited 10 seconds for the provider. When the timeout passed, it showed an error without asking the provider whether the payment had gone through.
- The error message asked customers to pay again.
- Each click on Pay created a new payment request. Our provider accepts an idempotency key, a unique value per order that makes it return the first result instead of charging again, but the checkout didn't send one.
- No alert watched payment errors. We found out from customers. The first complaint arrived 37 minutes after the first timeout, and Ana was paged after 61 minutes.
What went well
- Rosa escalated after the third matching email instead of answering each one separately.
- The provider dashboard showed the duplicate pairs clearly, so Ana confirmed the cause in 13 minutes.
- Every customer got their money back within two working days.
What didn't
- The first customer email arrived 37 minutes after the first timeout. Another 24 minutes passed before anyone paged Ana.
- Support had no saved reply for duplicate charges, so the first answers to customers were vague.
- Nobody had tested the checkout against a slow provider, only against a provider that was down.
Actions
- Rosa: email every affected customer with an apology and the refund confirmation (done 5 October)
- Ana: send the order number as an idempotency key with every payment request, by 16 October 2026
- Ana: on a timeout, ask the provider for the payment status before showing any error, by 16 October 2026
- Ana and Rosa: rewrite the timeout message so it tells customers not to pay again and that we will email them, by 16 October 2026
- Malik: alert the on-call phone when more than 5% of payments fail in any 10 minutes, by 23 October 2026
- Rosa: add duplicate charges to the support SOP, with the refund steps and a saved reply, by 30 October 2026
Look at what the example leaves out. There is no paragraph on whether Ana should have chosen a longer timeout. The 10 seconds appears as a fact about the checkout, and the action fixes the checkout so the length of the timeout matters less. The impact section admits the one number nobody knows, the orders lost while checkout was closed. The timeline runs until the last refund, not until the site came back, because the customers' problem lasted until Monday.
To copy it, keep the headings and the order, swap in your own incident and write the timeline before anything else.
Writing postmortems in Prompt Notebook
Prompt Notebook is ours, so read this part with that in mind. The post-mortem template opens as a page with a blameless note at the top and the headings from this guide: summary, impact, timeline, root cause, what went well, what didn't and actions. The actions are a to-do list with an owner at the start of each line. The sample is a deploy that delayed invoice emails for 3 hours and 20 minutes, so you see a finished postmortem before you replace it with your own.
You can also have the AI write a first draft. It drafts a page from one sentence. The Draft a variant with AI button on the template page starts a draft from a sample sentence about the double-charge incident in this guide. You insert, replace or discard what it suggests. Treat the draft as a structure to fill in. The timeline and the numbers have to come from your logs and your team.
For the review, share the page with comment access. People leave comments in threads on the draft, and you resolve each one as you fix it. Type @ to link the postmortem from your sprint board or task tracker, so the actions show up where the team plans its work. Once you have a few postmortems, Ask your workspace can answer a question like "which incidents involved the payment provider?" with numbered links to the pages the answer came from.
Start from the post-mortem template for the next incident on your list, or for the near miss nobody wrote up.
Frequently asked questions
What is the difference between a postmortem and a retrospective?
A postmortem looks at one incident, something that went wrong, and asks why it happened and what will stop a repeat. A retrospective looks back at a stretch of normal work, such as a sprint or a project, and asks what to keep and what to change. Both end with actions and owners. If you want the regular review rather than the incident write-up, read how to run a sprint retrospective or use the retrospective template.
How soon after an incident should you write the postmortem?
Start the timeline the same day or the next working day, while chat logs and memories are fresh. Hold the review meeting within a week. The clean-up doesn't have to be finished before you start writing, but the timeline isn't complete until it is.
Who should attend the postmortem meeting?
The people who handled the incident, the person who will own most of the actions and someone from each team the incident touched, such as support. Keep it small enough that everyone speaks. Managers can attend, as long as the person running the meeting keeps the discussion on the system and not on who to blame.
What does blameless mean in a postmortem?
It means the postmortem looks for the causes in how the system and the process worked, not in a person's character. It assumes everyone acted in good faith with the information they had at the time. People are still named as owners of the actions. Nobody is named as the cause.
How long should a postmortem be?
Long enough that someone who wasn't there understands what happened and why. For a small incident that can fit on one screen, like the example above. A long outage with many causes may run to several pages. If the summary is longer than a short paragraph, it belongs further down.