How to write a post-incident review (with a template)
A blameless post-incident review turns an outage into fixes. What to include, how to find the real cause, how to write action items that get done, and a copy-paste template.
· 7 min read · By the Spot Downtime team
The outage is over, the status page says Resolved, and everyone wants to move on. This is the moment that decides whether the same incident happens again. A post-incident review (also called a postmortem or retrospective) is a short written record of what happened, why, and what you'll change.
It doesn't need to be long or formal. A one-page document written within a few days, while memory is fresh, beats a perfect one that never gets written.
When to write one
Agree on triggers in advance so it isn't a debate each time. Reasonable ones:
- Customers were affected for longer than some threshold, such as 15 minutes.
- Data was lost or exposed.
- Someone had to be paged outside working hours.
- The fix was a manual intervention, such as a rollback or restart.
- A near miss that would have been serious on a busier day.
Keep it blameless
“Who made the mistake?” is the wrong question. People make reasonable decisions with the information they have, and a system where one slip causes an outage is the real problem. Write about actions and conditions, not individuals: “the deploy script didn't check for the missing variable”, not “Sam forgot the variable”. If people fear blame, they hide details, and you lose the information you need.
What to include
Summary and impact
Two or three sentences: what broke, for whom, and for how long. Be specific and measurable: which pages or endpoints, what fraction of requests failed, how many customers wrote in. Use numbers from your monitoring and logs rather than estimates.
Timeline
A list of timestamps in UTC: when the change was deployed, when the problem began, when it was detected, who responded, what was tried, and when it was fixed. Include the dead ends. They show what was confusing at the time.
Detection
How did you find out: an alert, or a customer? The gap between the problem starting and someone knowing is often the cheapest thing to improve. Note three durations:
- Time to detect: start of impact to the first alert.
- Time to respond: first alert to someone working on it.
- Time to resolve: start of impact to full recovery.
Root cause and contributing factors
Keep asking “why” until you reach something you can change. One cause is rare; several things usually line up.
Impact: checkout returned 500 for 22 minutes.
Why? The app lost its database connection pool.
Why? A migration held a table lock, and requests queued.
Why? The migration ran during peak traffic.
Why? Nothing in the deploy process flags long-running migrations.The last line is the useful one. “The migration was slow” is a symptom; “our process doesn't catch risky migrations” is something to fix.
What went well and what didn't
Record the things that helped, such as a clear runbook or a fast rollback, as well as the gaps, such as an alert that fired late or a dashboard nobody could find. This keeps the review balanced and tells you what to protect.
Action items
This is the part that matters. A good action item is specific, has one owner and has a date. Compare:
- Weak: “Improve migration safety.”
- Strong: “Add a CI check that fails migrations that lock a table for more than 5 seconds on a copy of production data. Owner: Priya. Due: Nov 12.”
Aim for a handful of items you will really do. Track them in your normal issue tracker, not only in the document, and check on them at your next team meeting.
A template to copy
# Incident review: <short title>
Date: <YYYY-MM-DD> Severity: <low / medium / high>
Author: <name> Status: <draft / reviewed>
## Summary
<What broke, who was affected, how long.>
## Impact
- Duration: <start - end, UTC>
- Affected: <pages, endpoints, customers>
- Failed requests: <number or percent>
## Timeline (UTC)
- 14:02 Deploy of <change> started
- 14:07 Error rate rose
- 14:10 Monitor alert fired
- 14:12 Acknowledged, investigation started
- 14:24 Cause identified
- 14:31 Rolled back, recovery confirmed
## Detection
<How we found out. Time to detect / respond / resolve.>
## Root cause and contributing factors
<Chain of "why", ending in something we can change.>
## What went well
-
## What went poorly
-
## Action items
| Action | Owner | Due | Issue |
|--------|-------|-----|-------|
| | | | |Running the review
- Collect the data first: alert history, logs, deploy records, chat transcript, and the status page updates you posted.
- Draft the timeline before the meeting so the discussion starts from facts.
- Hold a short meeting, 30 to 45 minutes, with the people involved. Focus on causes and fixes.
- Publish the review internally. Share a shorter version with customers if the incident was visible.
- Follow up on the action items until they're closed.
Sharing it with customers
For significant outages, a public summary builds trust: what happened, the impact, what you've changed. Skip internal names and blame, keep it factual, and don't promise what you can't deliver. The status page updates you posted during the incident are the first half of this story; see how to write incident updates customers trust for that part.
Use your monitoring data
To put a number on the cost of the incident, or to see how it affects your uptime target for the month, these free tools help:
Downtime cost calculatorEstimate what an outage costs in lost sales and work time, per minute, per hour and per year.Also see what 99.9% uptime really means for how many minutes of downtime each target allows, and how to reduce false alerts if the review shows noisy alerts delayed the response.
Get new guides by email
Practical posts on monitoring, outages, error fixes and on-call, when they're published. No spam.
Keep reading
- Incidents · Status pagesWebsite down message to customers: templatesCopy-ready messages for when your website or app is down: a status page update, banner, email, social post, support auto-reply, maintenance page and the all-clear.November 2, 2026 · 6 min read
- Incidents · Status pagesHow to write incident updates customers trust (with templates)During an outage, what you say matters almost as much as how fast you fix it. A simple four-stage structure, ready-to-use templates, and the mistakes that make customers lose trust.October 2, 2026 · 4 min read