incident-postmortem git:20260712.59c5852A

Immutable. This exact content never changes and is served at /api/v1/blob/b50b0314b58c57b0.

---
name: incident-postmortem
argument-hint: "[incident name or ID]"
description: Write a blameless post-incident review (post-mortem / RCA) that documents what happened, the timeline, root cause analysis, impact assessment, and concrete action items to prevent recurrence. Follows Google SRE blameless post-mortem culture.
intent: >-
  Produce a blameless post-mortem that transforms a production incident from a painful failure into a permanent improvement in system reliability. The core principle is blamelessness: incidents are caused by systemic failures, not individual mistakes. Attacking people instead of systems destroys the psychological safety that enables honest post-mortems, which are the only post-mortems worth writing. A good post-mortem has a precise timeline, a multi-layer root cause analysis (not just the proximate cause), a quantified impact, and specific, actionable, owner-assigned items with deadlines - not vague intentions.
type: component
theme: engineering-docs
best_for:
  - "After any production incident affecting users or SLA"
  - "After any near-miss that could have caused user impact"
  - "Building an organizational culture of continuous reliability improvement"
  - "Satisfying compliance or contractual obligations for incident reporting"
scenarios:
  - "Write a post-mortem for last night's payment processing outage"
  - "Document the root cause of the database connection exhaustion incident"
  - "Create a blameless review of the API timeout that affected 15% of users"
estimated_time: "30-60 minutes"
license: MIT
compatibility: Designed for Gemini (Antigravity), Claude Code, Cursor/Windsurf, Kimi Code, Codex/Copilot
---

## Purpose

Produce a blameless post-mortem that captures what happened, why it happened at every causal layer, and what specific, measurable actions will prevent recurrence.

**A post-mortem that blames a person is a post-mortem that will not be written honestly next time.** The goal is to find and fix system failures, not to assign individual culpability.

## Input

**Works best with:** A description of the incident.
**Also valuable:** Timeline of events, monitoring data, the alert that fired, what was done to mitigate, any on-call notes from the incident.

**Example invocation:** `Write a post-mortem for the incident on 2026-07-09 where the payment gateway returned 500 errors for 22 minutes affecting 8% of payment attempts. The root cause was a database connection pool exhaustion triggered by a slow query introduced in the v2.3.0 deployment 2 hours earlier.`

## Key Concepts

### Blameless Culture (Google SRE)
People do not cause incidents. **Systems do.** When an engineer makes a mistake that leads to an incident, the real questions are:
- Why did the system allow that mistake to have this impact?
- What alerting, testing, or deployment control would have prevented it?
- What process would have caught this before production?

Blameless does not mean consequence-free. It means the post-mortem focuses on systemic remediation, not individual punishment.

### Five Whys (Root Cause Analysis)
Do not stop at the proximate cause. The proximate cause is almost always "a bad change was deployed." The real causes are at least 4 Whys deeper:
- Why did the change cause the failure? (technical root cause)
- Why was the change deployed without detecting this? (testing gap)
- Why did monitoring not alert earlier? (observability gap)
- Why was the impact this broad? (blast radius issue)

### Severity Levels
| Severity | Definition | Example |
| :--- | :--- | :--- |
| SEV-1 | Complete service outage; all users affected | Payment gateway returning 100% 5xx |
| SEV-2 | Partial outage; significant user impact | 20% of payments failing |
| SEV-3 | Degraded performance; subset of users affected | p99 latency > 2s for 15 min |
| SEV-4 | Minor issue; minimal user impact | Admin panel slow for 5 min |

## Application

### Phase 1: Socratic Clarification & Brainstorming (Mandatory Interview)
Before writing any postmortem, you MUST interrogate the user's initial input, identify gaps, and ask **3-5 targeted clarifying questions** to dig deeper. Do NOT generate the template yet.
Ask questions to resolve:
1. **Symptom & Detection**: How was the incident first noticed (e.g. customer support ticket, automated alarm, internal observation)?
2. **Timeline points**: What are the key timestamps (incident start, detection, mitigation, complete resolution)?
3. **Immediate fix**: What temporary or permanent mitigation was performed to restore the service?
4. **Failure impact**: What is the estimated business or database impact (e.g. amount of failed requests, transaction losses)?
*Wait for the user's response to these questions before drafting the final postmortem.*

### Phase 2: Document Generation
1. Write the timeline from the first symptom to full resolution with exact timestamps.
2. Perform Five Whys to identify root causes at every layer.
3. Quantify the impact precisely.
4. Define specific, assignable action items - not vague intentions.
5. Share with the team within 24-48 hours of resolution.