The incident is over. Now what? A practical postmortem guide for vibe projects

The incident is over, the service is back, someone posts "recovered" in the group chat — and then what? For many solo developers and small teams, the answer is: then nothing happens. The next time the same incident comes around on a different date, whoever is on call troubleshoots by gut feeling, and if a postmortem document exists at all, it says little more than "be careful next time." This guide covers the other half of the work: how to write an incident postmortem that is actually useful, so each incident charges its tuition fee only once.

First, a boundary. An earlier guide on this site covered the incident runbook for indie developers — what to do while the incident is happening: severity levels, stopping the bleeding, rollbacks, external communication. A postmortem is the next leg of that relay, starting after recovery, with a different goal: response optimizes for speed, postmortem optimizes for accuracy — laying out the causal chain clearly and pinning changes to owners and deadlines. Used together, the runbook handles firefighting and the postmortem handles fire prevention; either one alone is only half the routine.

All examples in this article are fictional: suppose you run a small tool called "Listbird," and one morning users report that their task lists will not open. Every timeline, number, and name below is invented purely to demonstrate the writing method; the method itself can be applied directly.

Step 1: Nail the timeline before discussing causes

The first page of a postmortem should not be a cause analysis but a timeline. Causes can be debated; times cannot be fuzzy. Three rules for writing a timeline: record only verifiable facts, not speculation; cite the source of each entry (monitoring alerts, deploy records, chat logs, user reports); and describe impact from the user's perspective, not the server's — "09:12 users start reporting blank lists" is closer to the real cost of the incident than "09:12 API 500 rate rises."

For "Listbird," a decent timeline looks like this: 08:47 deploy v2.4.1 (change: caching added to the task-list endpoint); 09:12 first users report lists will not open; 09:20 on-call confirms it is not isolated, error rate 38%; 09:31 root cause located: cache-key collision, old and new versions sharing a prefix, old data format misread by new code; 09:40 rollback to v2.4.0; 09:55 error rate back to baseline; 10:20 recovery confirmed and public notice posted. Notice there is no judgment like "the cache was done badly" in the timeline — only "what was done, what was observed." Judgments belong in the next section; mixing them in turns the postmortem into a debating floor.

Step 2: Dig causes down to "the system allowed it to happen"

The most common postmortem flaw is stopping at the first layer of cause: "a cache-key collision caused the outage." That sentence is true but useless — it does not tell you how to prevent the next one. The effective method is to ask "why" at least three layers deep: why did they collide? Because old and new versions shared a cache-key prefix and there was no key-naming convention at release time. Why was it shared? Because cache-key naming had no checklist, and review only covered business logic. Why did review miss it? Because the release checklist had no "cache-key change" item, and the deploy process did no canary validation.

Dig to the third layer and the changes surface by themselves: add a cache-key naming convention, add an item to the release checklist, canary critical endpoints at 10% before full rollout. A postmortem that stops at the first layer can only produce unenforceable advice like "be careful with caches." One more red line: a postmortem does not name and shame. Writing "the on-call engineer failed to notice" is meaningless; writing "the alert threshold was set too high, triggering only at a 38% error rate" points at something fixable. The readers of a postmortem should be your future self and whoever takes over — not a tribunal.

Step 3: Action items need an owner, a deadline, and an acceptance test

The second half of a postmortem document is an action table, and every row must answer four questions: what changes, who does it, by when, and how do we know it is done? A bad example: "Improve caching strategy (owner: TBD, deadline: ASAP)" — that sentence is equivalent to nothing. A good example: "Add a version prefix v2 to task-list cache keys, owner: Amu, shipping by November 12, acceptance: old and new versions coexist for 24 hours in canary with no collision alerts."

Action items also need priorities. Bleeding-stoppers (the key-naming convention, the checklist item) should land within a week; structural changes (automated collision detection for the cache layer) can be scheduled within a month, but must have an explicit date rather than "when there is time." A practical habit: the day the postmortem meeting ends, write the action items straight into your task tracker alongside normal work. Items that stay only in the document will, three months later, almost certainly be untouched.

Step 4: Running the meeting: one hour, five agenda items

A postmortem meeting does not need ceremony, but it needs structure. One hour, five agenda items: the first 10 minutes walk the timeline — the facilitator reads, participants correct factual errors only; the next 20 minutes discuss causes, aiming for an agreed causal chain rather than a culprit; then 15 minutes settle action items, confirming owner and deadline for each on the spot; 10 more minutes review the response itself — did on-call flow, alerts, or communication drag; the final 5 minutes confirm who writes up the document and when it goes out. The facilitator should ideally not be someone directly involved; people involved tend to defend their own judgment without noticing.

Two details worth insisting on. First, the postmortem document should be visible internally, at least to the whole team; a hidden postmortem is an unwritten one, and newcomers will step into the same hole. Second, revisit regularly: spend 20 minutes each month scanning the action items from recent postmortems to see which ones slipped. A postmortem's value is not in how beautifully the document is written but in whether the action items actually landed — and the overdue list itself becomes material for the next postmortem.

A lightweight template for small teams: five sections are enough

Solo developers or teams of two or three do not need a big company's postmortem process, but five sections are worth keeping: summary (what happened, how big the impact was, how long it lasted), timeline (factual entries with sources), cause analysis (at least three layers of why), action items (what, who, deadline, acceptance test), and lessons learned (what could improve in the response process). Those five sections usually run one to two pages and take half an hour to write. Keep the template in your repository and copy it for each incident instead of reinventing the format — it saves more effort than it costs.

A final, less comfortable but true point: the hardest part of a postmortem is not the method but the mindset. Right after an incident, the two easiest things to do are to move on quickly or to find someone to blame; a postmortem demands the counterintuitive third option — lay the wound open, tell it in chronological order, and then change the conditions that allowed it. Teams that can do that see fewer and fewer incidents; teams that cannot will see the same incident return under a different date. Your next incident is already waiting for you to write the previous postmortem.

Building a postmortem culture: a three-month plan from the first document

Writing one postmortem is easy; building the habit is hard. Here is a three-month plan. Month one, do one thing only: write the first five-section postmortem within 48 hours of the next incident — imperfection is fine, existence is the win — and put the template in the repository with action items entering the task tracker the same day. Month two, do two things: backfill a postmortem for the most instructive past incident and add it to new-hire reading, so postmortems start preventing mistakes for newcomers; and revisit last month's action items to see which slipped and why — chronically overdue items are usually scoped too big or too vaguely, and need splitting. Month three, do one thing: connect postmortems to the release process, adding a checklist item — "have relevant past postmortems been reviewed for this change?" — especially for high-risk areas like caching, permissions, and payments. At that point the postmortem stops being a post-incident remedy and becomes a pre-release precaution. Three months in, the meeting conversation shifts from "how did this happen again" to "which problems did we have fewer of this time" — the sign that the culture is taking root.

One more note on storage: file the postmortem with its monitoring screenshots, deploy records, and public-notice links, somewhere the whole team can find — a fixed directory in the repository or a shared docs library — named by date and incident with a one-line summary. Many teams' postmortems are not unwritten but unfindable, scattered across personal machines and chat logs. And keep revisions traceable: if later evidence corrects the analysis, append a revision note rather than silently editing the original. A postmortem's credibility comes from its traceability; editing it silently dismantles exactly that.