Make incident reviews useful to the next person on call
Turn incident reviews into searchable operational knowledge with clear symptoms, tested actions, decision reasons and follow-up ownership.
An incident review can explain what happened beautifully and still fail the next person facing the same symptoms. The missing piece is often the connection between the historical story and an action someone can safely take now.
Keep the review, but extract the operational knowledge it produced.
Separate the timeline from the guidance
The timeline should preserve what was known at each stage. Current guidance should state what the team now believes, what has been fixed and what remains uncertain.
Without that distinction, an AI assistant may retrieve an early hypothesis and present it as the final cause. Label preliminary observations and link them to the confirmed finding or to an explicit unresolved status.
Capture symptoms people can search for
Record the visible symptoms, affected component, relevant error messages and conditions that distinguished this incident from similar ones. Use the language an on-call teammate would search during an interruption.
Do not include secrets, customer payloads or unrestricted log dumps. Link to access-controlled evidence when the underlying data is sensitive.
Turn lessons into owned changes
“Improve monitoring” is not a completed lesson. Name the specific gap, the intended change, the owner and the evidence that will show the change works.
For a runbook update, separate observation steps from actions that change the system. Note prerequisites, expected results, stop conditions and when to escalate. An assistant should not infer permission to execute a disruptive step merely because that step appears in a past incident.
Check whether the advice still applies
Architecture changes can invalidate an otherwise useful incident record. Link the guidance to the relevant system version or current owner, and revisit it when the component changes.
At the next review, ask a teammate unfamiliar with the incident to find the right record from the symptoms alone. Then ask them to explain the next safe action. If they cannot, improve the structure and links before adding more prose.
The value of an incident review is partly historical, but its operational value is whether the next person can recognise the situation and act with better information.