✏️ The Readability Pass: Making Postmortems People Actually Finish

Here’s an uncomfortable truth about your last postmortem: most of the people it was written for skimmed the summary, scrolled past the timeline, and closed the tab. Not because they don’t care, but because the document was a dense slab of passive-voice cause chains with three undefined acronyms in the first paragraph, and they had eleven other tabs open. The analysis was good. The delivery failed. And a postmortem whose lessons don’t reach anyone’s head is, functionally, a postmortem that didn’t happen.

Readability is not a cosmetic layer on top of the “real” postmortem. It’s the delivery mechanism for everything the analysis figured out. And it’s the pass almost every author skips, because by the time the doc is done they are completely sick of it and have no appetite left for an editing round. This is the lowest-stakes, highest-comfort place to hand work to a model — with one strict boundary.

Structure first, sentences second

There are two kinds of editing a postmortem needs and they are not the same job. The first is structural: does the summary deliver the point in thirty seconds, does impact come before mechanism, are the sections in the order this reader needs them? The second is line-level: undefined jargon, run-on causal chains, passive constructions that hide who did what, walls of text that should be a list.

Do them in that order. There’s no point polishing a sentence that’s in the wrong section, and the structural problems are the ones that actually lose readers — someone bounces off a postmortem because they can’t find the impact, not because a verb was passive. I have the model do a structure pass first and propose reordering, not rewriting, where shape is the problem.

Edit this postmortem for readability. Audience: <on-call eng / EM /
mixed>.

1. STRUCTURE: Is the summary skimmable in 30 seconds? Is impact
   stated before mechanism? Are sections in the right order for
   this audience? Suggest reordering, not rewriting.
2. LINE EDIT: Flag undefined jargon/acronyms, run-on cause chains,
   passive voice that hides what happened, and walls of text that
   should be lists or a table. Propose tighter wording inline.
3. TIMELINE: Are entries parallel, scannable, free of editorializing?
4. TAKEAWAYS: Is the single most important lesson visible without
   reading the whole doc? Suggest an "if you read nothing else" line.
5. Flag anything that reads as blame; propose neutral wording.

STRICT RULE: Do NOT change any fact, number, timestamp, or causal
claim. If a sentence is unclear because the underlying fact is
ambiguous, flag it [AUTHOR: clarify] — do not guess.

Draft: <paste>

The strict rule is what makes this safe

That last instruction is the entire reason you can run this on a real incident doc. An editing pass has two ways to corrupt a postmortem while appearing to improve it, and both are seductive.

The first is guessing at an ambiguous fact to smooth a sentence. A human editor who hits “the service degraded around the time the cache was, we think, partially evicted” will be tempted to tidy it into “the cache eviction degraded the service.” That’s cleaner and it might be wrong — now your postmortem asserts a causal claim the data didn’t support, in nicer prose. Forcing the model to flag ambiguity as [AUTHOR: clarify] instead of resolving it keeps the polish from outrunning the facts.

The second is softening a hard finding into something more comfortable to read. Tightening is allowed; weakening is not. “The deploy had no rollback plan and we improvised one live under pressure” should not become “the rollback process had room for improvement.” The first sentence is a finding. The second is corporate fog. A good readability pass makes the doc clearer, never gentler about what actually happened.

What it catches

On a real draft the inline edits look like this:

• Summary, ¶1: “Following an anomalous condition in the upstream dependency’s behavior, degradation was experienced by a subset of requests.” → “Checkout requests failed for ~12 minutes after the payments provider started returning 503s.” (Active voice, impact first, no jargon. Same facts.)
• Structure: The customer impact is in paragraph 4. Move it into the summary — it’s the first thing every reader needs.
• Timeline: Entries mix tense and editorialize (“unfortunately the alert was missed”). Make them parallel and neutral: state what happened, not how you feel about it.
• Takeaway: No single lesson stands out. Suggested “if you read nothing else” line: “A burn-rate alert that already existed had a threshold too loose to fire — that’s the one-line fix.”
• [AUTHOR: clarify]: “the cache may have contributed” — did it, or is this speculation? The doc states it as fact later.

Every one of those makes the doc more usable without touching what’s true. The active-voice rewrite is the same facts in fewer words; the [AUTHOR: clarify] flag caught a place where a hedge had hardened into an assertion two sections apart.

The author owns every change

The model proposes; the author disposes. This isn’t ceremony — the author is the only one who knows whether an ambiguity flag is “yes, clarify that” or “no, the hedge is correct and the later assertion is the bug.” Accept the structural moves and the clean line edits freely; treat every [AUTHOR: clarify] as a real question about the facts, not a styling suggestion. The whole arrangement only works because the human stays the authority on what’s true and the model stays the editor of how it reads.

The readability prompt is in the prompts library, and it’s the natural last step after the QA pass that checks for missing sections and unsupported claims — QA confirms the doc is complete and honest, readability makes sure someone finishes it. For the document standards it polishes, the blameless postmortem guide sets the bar.

The best analysis in the world loses to a wall of text. Spend the fifteen minutes — or hand them to a model that won’t touch your facts — and write the postmortem people actually finish.