How to Write Incident Postmortems and Runbooks in Plain Markdown

Quick answer

An incident postmortem template in plain Markdown needs six parts: an incident summary, a timestamped timeline, the root cause and contributing factors, an impact assessment, action items with owners and due dates, and lessons learned. Its companion document — the runbook — is a separate file with the exact commands a responder runs next time. You don't need dedicated incident-management software for any of this. A .md file in your repo, written while the details are still fresh, beats a half-filled wiki page every time.

Step-by-step

Write the incident summary and timeline as a table

Open with two or three sentences: when it started, when it ended, what was affected, who noticed. Then build the timeline as a table, not a paragraph:

| Time (UTC) | Event | Details |
|---|---|---|
| 14:02 | Alert fired | p99 latency crosses 2s on checkout-api |
| 14:06 | On-call acknowledges | Confirms error rate spike in dashboard |
| 14:19 | Rollback started | Reverting deploy #4821 |
| 14:24 | Latency recovers | p99 back under 300ms |

Pull the timestamps from alerts, deploy logs, and chat history — not from memory. Google's SRE book frames the whole exercise around facts over opinions, and a timeline reconstructed a week later from someone's recollection is exactly the soft spot a formal review will catch. A Markdown table keeps every row scannable, and it's easy to diff in a pull request when someone corrects a timestamp later.

Capture root cause and contributing factors

Separate the trigger from what made it worse. A bad deploy might be the trigger; a missing rollback runbook and an alert that fired ten minutes late are contributing factors, and each deserves its own line. The usual advice is to ask "why" repeatedly until you reach a systemic cause — not "the engineer forgot a step," but "the deploy checklist didn't have that step in it."

Blameless culture is a writing discipline here, not just a value statement. Google's SRE book puts it plainly: assume everyone involved had good intentions, and investigate why they had incomplete or incorrect information at the time, not who to blame for having it. If a sentence in your draft names a person as the cause, rewrite it as a sentence about the system that let that happen.

Turn action items into a task list

An action item needs four fields to survive past the review meeting: the task, an owner, a due date, and a status. Skip any of those, and it quietly becomes a lesson nobody acted on. Written as a nested task list, it's easy to scan and easy to check off:

## Action items
- [ ] Add checkout-api rollback step to deploy checklist — @priya — due 2026-10-07
- [ ] Lower the p99 alert threshold to 1.5s — @dan — due 2026-10-03
  - [x] Threshold changed in staging
  - [ ] Threshold changed in production

Write the companion runbook

A postmortem and a runbook solve different problems. The postmortem is a record of what happened. The runbook is a tactical guide a responder follows during the next incident — the exact commands to run, the dashboards to check, the rollback to execute. A postmortem's most useful action item is often "write or fix the runbook that would have made this faster."

A runbook you can actually trust holds up to five checks: it's Actionable (commands, not narrative), Accessible (where responders already are, not three folders deep), Accurate (current, version-controlled), Authoritative (one copy, not three conflicting ones), and Adaptable (updated right after the next postmortem — the same way you'd update an architecture decision record once a decision changes). Skip that update, and the next on-call engineer inherits a runbook with one outdated command, which is often worse than no runbook at all.

Common problems and fixes

The timeline gets written from memory, days later. Pull it from alerting, deploy logs, and chat exports the same day, while the export is still one click away.

The draft reads like it's assigning blame. Reread every sentence that names a person doing something wrong, and rewrite it as a sentence about the system: not "Dan pushed a bad config," but "the config validation step didn't catch a missing field before deploy."

Action items pile up and never close. Require an owner and a due date before you consider the postmortem finished, and track status in the doc itself instead of a separate ticket nobody revisits.

The runbook is technically there, but nobody trusts it. That's usually a staleness problem, not a writing problem. Add "update the runbook" as a standing action item on every postmortem that used one, and review it on a fixed quarterly schedule even when nothing went wrong.

Frequently Asked Questions

What's the difference between a postmortem and a runbook?

A postmortem is a record you write after an incident is resolved — it explains what happened, why, and what you're changing so it doesn't happen again. A runbook is written ahead of time and used during an incident: it's the step-by-step commands a responder follows to fix a specific known problem. They're companion documents. A good postmortem's action items often include writing or updating the runbook that would have made the incident faster to resolve.

Do you need special postmortem software, or is plain Markdown enough?

Plain Markdown is enough for most teams, especially small ones. The anatomy that matters — summary, timeline, root cause, action items, lessons learned — is just headings and a table. A .md file in your repo is faster to start under pressure than opening a new tool, easier to search later, and simple to link from a pull request or an issue. Dedicated incident tools add integrations like paging and status pages that are genuinely useful at scale, but they're not what makes a postmortem good.

How detailed should the incident timeline be?

Detailed enough that someone who wasn't there could follow it — but built from data, not memory. Pull real timestamps from alerts, deploy logs, and chat history rather than reconstructing them from what people remember. Each row needs a time with timezone, what happened, and enough detail to explain why that moment mattered. Skip the commentary that doesn't help a future reader follow the sequence.

Who should write the postmortem — the person who caused the incident?

Whoever is closest to the facts, usually the incident's primary responder. But it should never feel like an assignment of blame. Blameless culture means the document investigates why a person or system had incomplete information, not who to point at. In practice, it's often a shared document that other responders add timeline entries and context to.

Doing this with Carets

A postmortem gets written in the hour after an incident, on whatever's fastest to open — which is exactly when a native, fast Markdown editor beats waiting on a browser tab to load. Carets keeps the timeline table, the task-list action items, and the runbook as separate files in one project, so the postmortem and the runbook it produces sit next to each other instead of scattered across a wiki and a chat thread. Everything stays plain text, so both documents are portable enough to copy straight into a pull request or commit alongside the fix they describe.

Get Carets on iPhone, iPad, and Mac from the App Store.