The change postmortem — what we learned and what we change next

A change without a postmortem is a change the organisation cannot learn from. The change applies, the incident (or non-incident) ends, and the lesson is either captured in a document or lost in Slack. The postmortem is the closing artefact of the change record: it is what the team writes after the change has been live long enough to know whether it worked. The postmortem is not the change record; the postmortem is the record of what the team learned from the change and what they will change next.

The change record versus the postmortem

The change record captures what was done: the what, why, when, who, where, how, and rollback. The postmortem captures what was learned: what worked, what did not, what surprised the team, and what will be different next time.

flowchart LR
    CR["Change record: what was done"] --> LIVE["Change runs in production"]
    LIVE --> OBS["Observation window"]
    OBS --> PM["Postmortem: what was learned"]
    PM --> AI["Action items as PRs"]
    AI --> CR2["Next change record"]
    CR2 --> LIVE

• Change record. Snapshot at the time of the change. Fixed point in time. Lives in the pull request.
• Postmortem. Reflection after the observation window. Captures the gap between expected and actual. Lives in a postmortem document or a discussion.
• Action items. Pull requests with the same audit properties as the change that prompted them. The postmortem’s output is a new change record.

A team that writes change records but not postmortems captures the what but not the why it worked. A team that writes postmortems but does not turn action items into pull requests captures the why but does not change.

The four rules of a blameless postmortem

A blameless postmortem focuses on systems and signals, not on individuals. The four rules:

1. Name the system, not the person. “The deploy pipeline ran without a manual gate” is a system statement. “Alice forgot to add a manual gate” is a person statement. The postmortem names the system.
2. Describe the contributing factors, not the cause. Most incidents have multiple contributing factors; attributing a single cause to one engineer is rarely accurate and is always counter-productive.
3. Quote the artefacts, not the people. The timestamp comes from the pipeline log; the rationale comes from the PR description; the rollback comes from the revert PR. The postmortem quotes the artefacts.
4. Close with action items as pull requests. The postmortem is not a complaint; it is a list of changes. Each action item is a pull request.

flowchart TB
    R1["Rule 1: name the system"] --> R2["Rule 2: contributing factors"]
    R2 --> R3["Rule 3: quote artefacts"]
    R3 --> R4["Rule 4: action items as PRs"]
    R4 --> NEXT["Next change record"]

A postmortem that violates any of the four rules is a postmortem that will not be read by the next engineer who could have benefited.

Action items as pull requests

The postmortem’s output is a list of action items. Each action item is a pull request with the same audit properties as the change that prompted the postmortem: template, reviewers, status checks, merge record.

TITLE="Add CODEOWNERS entry for /infra/payments/"
BODY=$(cat <<'EOF'
## What
Adds /infra/payments/ to CODEOWNERS with
@payments-platform-team.

## Why
Postmortem PM-2026-08-21: a pull request merged to
/infra/payments/ without a CODEOWNERS approval because
the path was unmapped.

## When
This week.

## Who
Author: alice; Approver: bob.

## Where
Repository: acme/infrastructure; path: .github/CODEOWNERS.

## How
Apply CODEOWNERS change; verify with a test PR.

Refs: PM-2026-08-21
EOF
)
gh pr create \
  --title "$TITLE" \
  --body "$BODY" \
  --base main \
  --head fix/codeowners-payments \
  --reviewer bob \
  --label "postmortem-action,payments"

A postmortem action item that is not a pull request is a wish. A postmortem action item that is a pull request is a change record with the same audit properties as any other change.

The postmortem repository

The postmortem repository is a separate Git repository where postmortems live as Markdown files. Each postmortem is a file; each file has a frontmatter with the date, the change record link, the action items list, and the lessons learned.

postmortems/
  2026-08-21-payments-key-rotation.md
  2026-08-15-checkout-hpa-bump.md
  2026-08-08-iam-policy-merge.md

A directory of postmortems is searchable by date, by service, by tag. An auditor who asks “what have you learned from payment changes in 2026?” can answer with a git log and a directory listing.

Production discipline

1. Every change has a postmortem. Not every change has an incident; every change has an observation window and a postmortem at the end of it.
2. The postmortem is blameless. The four rules are enforced by review: a postmortem that names a person is rewritten.
3. Action items are pull requests. A postmortem without action items is a complaint; a postmortem with action items as PRs is a change record.

Cross-course references

• This course, Part LXIV (Auditability) - the audit chain the postmortem completes.
• This course, Part LXXXVII (IncidentGitOps) - break-glass procedures that generate postmortems as part of the reconcile-back step.
• Kubernetes for Production Sysadmins - Parts XLI-XLIII (IncidentPostmortem) cover the incident-side postmortem process.

Quiz