Postmortem: a 5-section template

What you'll learn

• Use a 5-section template to structure a postmortem
• Turn a postmortem into actionable checklist items (not a complaint wall)
• Build a reusable postmortem library for your team / yourself

Version

Compatible with: dsh 0.1.1-rc.2 (compiled from SRE industry best practices + local incident case studies)

Why the DSH ecosystem needs postmortems

DSH's plugin ecosystem is still early: rapid plugin growth + multi-profile + sandbox + dual manifest + Cordis — any layer breaking becomes "my session just stopped". An ecosystem without a postmortem library will keep stepping on the same class of bug.

A postmortem isn't an admission of guilt — it's a structured record of root cause + mitigation + future defenses, so the team can locate similar symptoms within 5 minutes next time.

5-section template

Every postmortem has five fixed sections (h3 is fine, h2 reserved for the title):

1. Summary

Two sentences: what broke + impact + duration.

Example: 2026-08-15 14:32–14:47 UTC, in the web profile the modlens plugin intermittently failed to read PNGs (~30% users affected, 15 minutes). Root cause: sharp native module ABI incompatible after Node 22.23 upgrade.

2. Timeline

UTC timestamps + key events:

• 14:32 — user A first report; agent responds "image read failed"
• 14:35 — second / third user same symptoms; classified as common-dependency issue
• 14:38 — dsh --profile web --dump-resources shows sharp.so load failure
• 14:42 — rollback to last stable version (modlens 0.4.2)
• 14:47 — all affected users recovered

3. Root cause

Technical explanation — don't write "human error" or "bad luck"; root cause must be a mechanism:

[email protected] relies on Node 22's N-API v8. After Node 22.23 upgrades to N-API v9, the prebuilt sharp.so refuses to load (error code ERR_DLOPEN_FAILED). modlens 0.4.3 directly depends on [email protected] and did not declare a Node ABI range.

4. Mitigation

Immediate action + long-term defenses:

Immediate (within 24h):

• Roll back modlens to 0.4.2
• Add Node 22.23 known-incompatible notice to README
• Contact sharp maintainer

Long-term (within 1 month):

• Add node_abi_range field to dsh.bundle schema, validated at CLI install
• CI matrix tests (Node 22.20 / 22.23 / 22.24)
• modlens upgrades to [email protected]+ (ABI fixed)

5. Lessons

Portions that transfer to other plugins / teams:

• Plugins depending on native modules must declare ABI range — not just a line in README, but a structured field in the bundle manifest that the CLI enforces
• Rollback capability beats fix capability — 0.4.2 rolls back in 5 minutes vs 10 minutes of debugging + patching
• User reports are real probes — 3 users with the same symptom = a common-dependency issue; don't wait for the 4th

What NOT to write

• Don't write "we learned X" — that empty summary — must be actionable
• Don't assign blame (unless compliance requires it) — postmortems are blameless
• Don't rush to publish within 24h — first stabilize, fix, observe 48h, then write

How to convert postmortems into reusable checklist items

Append "Derived tasks" at the bottom of each postmortem:

## Derived tasks
- [ ] [dsh-cli#482](https://...) — bundle schema adds node_abi_range field
- [ ] [modlens#91](https://...) — upgrade sharp to 0.33+
- [ ] [deepseek-plugin.org#55](https://...) — "Install FAQ" tutorial adds ABI compatibility section

Tasks go in each repo's issues, not in the postmortem — the postmortem records "why this task exists", task progress lives in the issue tracker.

FAQ

How often should I write a postmortem?

Within 24h after every incident impacting ≥5% of users. Below that threshold, file it in the weekly "Incident Log" digest instead.

Can I write a postmortem while the incident is still ongoing?

No. First contain → observe 48h to confirm stability → then write. Writing mid-incident tends to miss the actual root cause.