How is a postmortem different from a decision record?

Under Defining a postmortem, the post says what sets a postmortem apart from a decision record and links the guide for those.

Where should postmortem files go, and what should they be called?

Under Naming and storing postmortem files, this post gives its own choice of folder and file name.

Should a postmortem name the person who made the mistake?

Under Keeping a postmortem readable later, one tip covers how this template treats people in the Causes field.

Postmortem template in Markdown: write up what went wrong

Bobby Huang · 2026-10-22

Under The postmortem template, this post sets out one fenced Markdown block for a new .md file, with a short list after it that explains each field.

Key takeaways

The section Defining a postmortem says what the file records and how it differs from a decision record.
The section A worked sample from Doe Holdings fills in the template for a made-up weekly report that went out with old figures.
Under A worked sample from Doe Holdings, the timeline is a list of time and event lines, and each action item names an owner and a date.
The section Naming and storing postmortem files suggests one dated file per postmortem and points to two guides on names and header fields.
The section Keeping a postmortem readable later gives short tips on causes, owners and the summary.

Something broke, someone fixed it, and now the details sit in a few heads. A postmortem template turns that into one plain Markdown file: what happened, who it hit, why it happened, and what to change so it doesn't happen again.

Below you'll find the template, what each of its fields is for, and one sample with every field filled. Whatever text editor you have open is enough. There's no install step.

Defining a postmortem

A postmortem is one brief .md file written after a problem has been found and fixed. The one in this post puts the events in order, names the causes, and ends with a list of actions that each have an owner and a due date. You write it once things are calm, so the facts are fresh and nobody is still putting out the fire.

This post treats incident report and incident review as other names for a postmortem. The template here is this post's own.

A decision record looks at a different moment. It is written when a choice gets made, and it keeps the options that lost along with the reasons. The template for decision records gives you a file for that job. A postmortem looks back at an event instead, so its center is the timeline and the follow-up work.

The postmortem template

Start a fresh .md file, paste the block in, and swap each placeholder line for your own words. Short labeled lines go at the top. Each longer part sits under a heading of its own, so each part is easy to find as you scroll the raw file.

# Postmortem: short name of what went wrong

Date: YYYY-MM-DD
Status: draft
Owner: name of the person writing it up

## Summary

Two or three sentences: what went wrong, for how long,
and how it got fixed.

## Impact

Who and what it touched, and by how much.

## Timeline

- YYYY-MM-DD HH:MM The first thing that went wrong.
- HH:MM Someone notices, and how they noticed.
- HH:MM What was tried.
- HH:MM The fix, and who made it.

## Causes

What made it happen, and what let it get as far as it did.

## What went well

- Something that helped the fix go faster.

## What to change

- Something to do differently next time.

## Action items

- The action. Owner: name. Due: YYYY-MM-DD.

Here is the job of each field:

Title. A heading that starts with "Postmortem:" and names the event in a few words, such as "weekly report sent with old figures".
Date. When the event started, in the form YYYY-MM-DD.
Status. Two values in this template: draft while you write, and done once the action items have owners and dates.
Owner. The one person who writes the file and keeps it up to date.
Summary. Two or three sentences for a reader who stops there. Write it last.
Impact. Who felt it, what it touched, and for how long. Put in numbers where you have them.
Timeline. One line per event, each starting with a time. The first line carries the full date, so later lines can give just the time.
Causes. What made the event happen, and what kept anyone from catching it sooner. A single event can have more than one cause.
What went well. The things that made the fix quicker. Keep them, so the next write-up can reuse them.
What to change. Plain statements of what should work differently.
Action items. One line per task, with one owner and one due date. Each line turns a point from What to change into work someone has agreed to do.

A worked sample from Doe Holdings

This copy has every field filled. Doe Holdings, plus Jane and John Doe, are invented names, and the event below is a made-up sample.

# Postmortem: weekly report sent with old figures

Date: 2026-10-06
Status: done
Owner: Jane Doe

## Summary

The weekly report for 2026-10-06 went out with September figures.
Jane Doe built it from a September copy still named figures-latest.md.
Jane Doe sent a fixed report the same afternoon.

## Impact

Twelve Doe Holdings staff read last month's figures for about
five hours. Staff used the old totals at one budget meeting and
met again the next day.

## Timeline

- 2026-10-06 09:00 Jane Doe sends the weekly report to staff.
- 10:30 John Doe asks why the totals match last month.
- 11:15 Jane Doe finds that figures-latest.md is a September copy.
- 13:40 Jane Doe makes the change and builds the report from figures-2026-10.md.
- 14:00 Jane Doe sends the fixed report with a short note.

## Causes

On 2026-10-03, figures-latest.md was renamed to figures-2026-10.md.
A September copy still sat in the folder under the old name, so the
report came from that copy. Nothing in the report said which month
its figures covered.

## What went well

- John Doe spotted the gap within two hours.
- The fixed report reached staff the same day.

## What to change

- Put the month of the figures in the report's first line.
- Move old figure files out of the folder when a file gets a new name.

## Action items

- Add the month to the report's first line. Owner: Jane Doe. Due: 2026-10-16.
- Move old figure files to an archive folder. Owner: John Doe. Due: 2026-10-13.

Look at the Timeline: each line starts with a time, and only the first one carries the date. Look at the Action items too. Each one is a plain list line with its owner and due date written out, so a reader can tell who acts next without asking anyone.

Naming and storing postmortem files

What this post picks is a postmortems/ folder with one dated file per postmortem, such as postmortems/2026-10-06-weekly-report-figures.md. The date is the day the event started, the same as the Date line, and the words after it name the event. Once a postmortem is done, it stays where it is, and later files can point to it by name.

For the words in the name, Markdown file naming conventions has sections on putting a year-first date at the front and on names that stay put. If you'd rather move Date, Status and Owner into a YAML header above the first heading, the front matter guide that covers status, date and owner goes through what those three fields stand for and the points to look at as you read them.

Keeping a postmortem readable later

Someone who opens the file in six months has the file and nothing else. These habits make that enough:

Spell things out. Write full file names, real numbers and the names of the people involved. Words such as "the fix from last time" tell a later reader nothing.
Point causes at steps and gaps. Name people in the Timeline for what they did and in Action items for what they own. In the Causes field, this template puts the step that let the event happen, and leaves blame out.
Give each action one owner. Two owners on one line can leave each of them waiting on the other.
Write the Summary after the rest. By then you know how the event ended, so the summary can say it in three sentences.

Some postmortems end with work that carries on into another session. The explainer on agent handoff files covers the parts of a file that passes unfinished work along, and a quick order for reading one. You can also hand the finished postmortem to your own agent along with that work.

To sum up a week of work for the people you work with, start from a weekly status report.

A bug report is for writing a problem down before it gets fixed, with steps someone else can follow to see the same thing.

Where Sashmark fits

Sashmark, planned for the desktop, is a reader plus editor for Markdown files, aimed at anyone whose AI agents write them. Right now it's still in development, with nothing out yet for you to try. A folder of postmortems, one file for each thing that went wrong, fits the sort of file set it is planned for.

See the planned features, the help pages and the roadmap for where each part stands.

Visit sashmark.com.

Questions

How is a postmortem different from a decision record?: Under Defining a postmortem, the post says what sets a postmortem apart from a decision record and links the guide for those.
Where should postmortem files go, and what should they be called?: Under Naming and storing postmortem files, this post gives its own choice of folder and file name.
Should a postmortem name the person who made the mistake?: Under Keeping a postmortem readable later, one tip covers how this template treats people in the Causes field.