Postmortem writing

Postmortem Writing

Use this skill after a meaningful failure, incident, rollback, release problem, or recovery effort when the goal is to learn clearly rather than simply retell the pain.

Goal

Turn a failure or unstable event into reusable engineering knowledge.

Focus on:

1. what happened
2. what impact it had
3. how it was detected
4. what changed or triggered it
5. what recovery happened
6. what the real lessons and action items are

Core Rules

1. Prefer facts before interpretation

Start by capturing observable facts:

• timeline
• symptom
• impact
• scope
• trigger or suspected trigger
• mitigation or recovery steps

Do not begin with blame, opinion, or untested conclusions.

2. Separate impact from cause

A good postmortem distinguishes:

• symptom: what was visible
• impact: what users/systems experienced
• trigger: what change or condition preceded it
• root cause: the deeper reason the failure was possible
• contributing factors: things that made the incident worse or harder to detect

3. Avoid blame-heavy writing

The goal is to improve systems, workflows, and decisions.

Prefer:

• "the system assumed..."
• "the release process did not verify..."
• "the change affected a shared path..."
• "detection was delayed because..."

Avoid reducing the postmortem to personal blame unless the user explicitly needs an accountability document.

4. Keep the timeline compact and useful

The timeline should help explain progression, not drown the reader.

Include:

• key change/release moment
• detection moment
• major triage decisions
• mitigation/rollback/hotfix moment
• recovery confirmation moment

5. Write action items that change future behavior

Good action items are:

• specific
• scoped
• testable
• tied to the failure mode

Weak action items include:

• "be more careful"
• "test better"
• "communicate more"

Prefer:

• add deployment verification for built assets
• add regression test for the failing path
• split risky shared-config changes into isolated worktrees
• define rollback criteria before next release

6. End with reusable lessons

A postmortem should leave behind:

• one or more engineering lessons
• one or more process lessons
• a short summary of what should change next time

Minis-Specific Workflow

Evidence sources

Use available Minis evidence such as:

• shell logs and outputs
• git diff/history
• browser-visible symptoms
• release/deployment notes
• triage or rollback notes
• local repro steps

Compact document bias

On Minis, prefer a concise but complete postmortem.

A good default structure is:

• summary
• impact
• timeline
• root cause and contributing factors
• recovery
• action items
• lessons learned

Link to earlier workflow steps

If you already used:

• incident-triage
• rollback-planning
• root-cause-tracing
• release-readiness
• deployment-verification

then reuse those findings rather than re-inventing the narrative from scratch.

Postmortem Sequence

Use this order:

1. Restate the incident/failure succinctly.
2. Summarize impact and scope.
3. Write the key timeline.
4. State the trigger, root cause, and contributing factors separately.
5. Summarize mitigation and recovery.
6. List follow-up actions.
7. End with lessons learned.

Common Postmortem Mistakes

Watch for:

• mixing facts with guesses
• writing a giant timeline with no prioritization
• describing symptoms but never naming impact
• describing the trigger but not the root cause
• vague action items with no change in behavior
• blame-heavy language that obscures system lessons
• omitting what recovery actually worked

Integration with Other Skills

• Use incident-triage notes as the starting point for impact, scope, and early timeline.
• Use rollback-planning notes for recovery sequencing and caveats.
• Use root-cause-tracing for the root-cause section.
• Use change-risk-review to identify what warning signs were missed before the change.
• Use release-readiness or deployment-verification if the failure involved shipping or environment mismatch.

Completion Checklist

Before calling the postmortem done, check:

• Is the incident summary clear?
• Is impact stated concretely?
• Is the timeline compact and useful?
• Are trigger, root cause, and contributing factors separated?
• Are mitigation and recovery described accurately?
• Are action items specific and useful?
• Are the lessons reusable for future work?

Response Template

• Incident summary:
• Impact:
• Timeline:
• Trigger:
• Root cause:
• Contributing factors:
• Recovery:
• Action items:
• Lessons learned:

Example Triggers

• "Write a postmortem for this incident."
• "Turn this rollback/debugging session into lessons learned."
• "Summarize what happened, why, and what should change next time."
• "Help me write a blame-free engineering postmortem."
• "Convert this failed release into a useful postmortem."