imtiazrayhan Write a learning document grounded in evidence. Preserve uncertainty and avoid blame, invented precision, and action items that cannot be verified.
Workflow
- Establish the incident window. Collect detection, start, mitigation, recovery, and full-resolution times. Normalize timestamps to one timezone while preserving source links.
- Build the factual timeline. Merge alerts, deploys, logs, traces, tickets, and responder notes. Separate observed facts from inference. Resolve contradictions or list them explicitly.
- Quantify impact. Record affected users, regions, tenants, requests, data, duration, revenue or operational impact, and SLO/error-budget consumption. State measurement gaps.
- Explain system behavior. Describe the trigger, contributing technical and organizational conditions, failed or absent safeguards, and why the impact propagated. Avoid stopping at the first human action or component failure.
- Evaluate detection and response. Explain what detected the incident, what should have, time to acknowledge and mitigate, which runbooks or tools helped, and where responders lacked information or safe controls.
- Record what went well. Preserve defenses, decisions, automation, and coordination worth repeating—not as praise filler, but as operational knowledge.
- Create corrective actions. Each action needs a specific change, owner, priority, due date, and verification method. Balance prevention, detection, containment, recovery, and learning; avoid “be more careful” and “add monitoring” without a defined signal.
- Review sensitive detail. Remove secrets and unnecessary personal data. Coordinate disclosure for security, legal, or customer-facing facts without erasing engineering evidence from the controlled internal record.
- Track closure. Link actions to tickets and define who verifies completion and effectiveness. A merged change is not complete until the intended risk reduction is tested.
[!WARNING] Do not convert an unknown into a root cause to make the document feel complete. Label uncertainty, preserve competing hypotheses, and assign an investigation action with evidence needed to resolve it.
Output
Create one Markdown postmortem containing:
- executive summary and quantified impact
- incident and response timeline with evidence links
- trigger, contributing conditions, and safeguard analysis
- detection, mitigation, recovery, and communication assessment
- what worked and what increased impact
- corrective-action table with owner, priority, due date, and verification
- open questions and explicitly labeled unknowns
- follow-up review date for action effectiveness