THE GITHTML FIELD GUIDE
Incident review template focused on evidence and follow-up
An incident review should explain what users experienced, how the team responded, what the evidence supports, and what will change. Separate the timeline from causal analysis. Use factual, blameless language, identify uncertainties, and assign concrete follow-up with owners and completion evidence rather than promising that the incident cannot recur.
Start with impact and scope
Record the incident window, affected service, observed user impact, and how those facts were established. If impact is still estimated, say so and describe the basis of the estimate. Do not turn missing telemetry into a claim that no users were affected. Google's postmortem guidance supplies the blameless learning context; the document itself should avoid evaluating someone's character or hindsight judgment. Explain what information responders actually had at the time. This keeps the review useful for improving the system instead of making it a defense of individual decisions.
Separate chronology from explanation
Build an illustrative timeline using timestamps, observations, and evidence links: an alert fired, a responder compared recent deployments, a dependency error was identified, and recovery was verified. Keep those events separate from hypotheses about why they happened. Use a consistent timezone and mark uncertain times as approximate. Include decisions that helped and observations that ruled out a hypothesis, not just the final successful action. Redact customer data and secrets from logs before attaching excerpts, and retain enough context to explain what each excerpt demonstrates.
- Impact: state what failed for users and what remained functional.
- Contributors: distinguish confirmed mechanisms from plausible but untested explanations.
- Follow-up: assign an owner, a due date, and evidence of completion.
Make learning observable
A useful action item changes a specific condition: add a missing alert, test a recovery path, clarify an ownership boundary, or remove an unsafe default. Replace improve monitoring with the exact failure signal and the verification expected. Avoid filling the list exclusively with document updates when the issue requires engineering work. Publish a review status and note unresolved questions. A portable HTML version is useful for reading the narrative, but the authoritative action tracker should remain identified so completed tasks and ongoing investigations are not mistaken for a frozen snapshot.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.