From 84679cb812fc3065d4c6e7e81fb8de882ef8d44e Mon Sep 17 00:00:00 2001 From: NIJO GEORGE PAYYAPPILLY Date: Wed, 21 Oct 2026 15:00:35 -0700 Subject: [PATCH] Improve incident-postmortem skill with Google SRE format and fishbone RCA - Follow the Google SRE post-mortem template (Detection, Resolution, Trigger, Where we got lucky, typed action items) - Add a fishbone (Ishikawa) step that feeds per-branch 5 Whys chains - Gather all incident inputs from the user; never invent details - Offer Markdown (default), HTML, DOCX (via md-to-docx) and PDF output - Move the template and a worked example into references/ Co-Authored-By: Claude Sonnet 5.5 --- docs/README.skills.md | 2 +- skills/incident-postmortem/SKILL.md | 235 ++++++++---------- .../references/fishbone-example.md | 81 ++++++ .../references/postmortem-template.md | 121 +++++++++ 4 files changed, 300 insertions(+), 139 deletions(-) create mode 100644 skills/incident-postmortem/references/fishbone-example.md create mode 100644 skills/incident-postmortem/references/postmortem-template.md diff --git a/docs/README.skills.md b/docs/README.skills.md index 055d5793fd..b614d6c8c9 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -243,7 +243,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [image-manipulation-image-magick](../skills/image-manipulation-image-magick/SKILL.md)
`gh skills install github/awesome-copilot image-manipulation-image-magick` | Process and manipulate images using ImageMagick. Supports resizing, format conversion, batch processing, and retrieving image metadata. Use when working with images, creating thumbnails, resizing wallpapers, or performing batch image operations. | None | | [impediment-prioritization](../skills/impediment-prioritization/SKILL.md)
`gh skills install github/awesome-copilot impediment-prioritization` | Ranks any list of impediments and their countermeasures using a value-stream scoring model (ROI, Cost to Implement, Ease of Deployment, Risk Factor) and a fixed prioritization formula. Use when someone asks to prioritize, rank, sequence, or triage impediments, countermeasures, remediation items, risks, findings, gaps, action items, or backlog entries; or mentions value-stream prioritization, A3 / lean countermeasure ranking, ROI vs. effort scoring, or building a remediation / improvement backlog. Works with GHQR findings, audit results, retrospective action items, risk registers, architecture review gaps, or any free-form `{impediment, countermeasure}` list. | `references/scoring-rubric.md` | | [import-infrastructure-as-code](../skills/import-infrastructure-as-code/SKILL.md)
`gh skills install github/awesome-copilot import-infrastructure-as-code` | Import existing Azure resources into Terraform using Azure CLI discovery and Azure Verified Modules (AVM). Use when asked to reverse-engineer live Azure infrastructure, generate Infrastructure as Code from existing subscriptions/resource groups/resource IDs, map dependencies, derive exact import addresses from downloaded module source, prevent configuration drift, and produce AVM-based Terraform files ready for validation and planning across any Azure resource type. | None | -| [incident-postmortem](../skills/incident-postmortem/SKILL.md)
`gh skills install github/awesome-copilot incident-postmortem` | Use when an outage, production incident, or significant service degradation has occurred and the team needs to write a structured blameless post-mortem. Triggers on phrases like "write a post-mortem", "incident review", "what went wrong", "outage report", "root cause analysis", or "RCA". Covers timeline reconstruction, contributing factor analysis, impact quantification, and action item generation with owners. | None | +| [incident-postmortem](../skills/incident-postmortem/SKILL.md)
`gh skills install github/awesome-copilot incident-postmortem` | Use when an outage, production incident, or significant service degradation has occurred and the team needs a blameless post-mortem / RCA document in the Google SRE format. Triggers on phrases like "write a post-mortem", "incident review", "what went wrong", "outage report", "root cause analysis", "RCA", or "fishbone". Collects incident inputs from the user, uses a fishbone (Ishikawa) diagram to surface candidate causes, drills the strongest branches with 5 Whys, and produces typed action items. Outputs Markdown by default, with HTML, DOCX, or PDF on request. | `references/fishbone-example.md`
`references/postmortem-template.md` | | [integrate-context-matic](../skills/integrate-context-matic/SKILL.md)
`gh skills install github/awesome-copilot integrate-context-matic` | Discovers and integrates third-party APIs using the context-matic MCP server. Uses `fetch_api` to find available API SDKs, `ask` for integration guidance, `model_search` and `endpoint_search` for SDK details. Use when the user asks to integrate a third-party API, add an API client, implement features with an external API, or work with any third-party API or SDK. | None | | [issue-fields-migration](../skills/issue-fields-migration/SKILL.md)
`gh skills install github/awesome-copilot issue-fields-migration` | Bulk-migrate metadata to GitHub issue fields from two sources: repo labels (e.g. priority labels to a Priority field) and Project V2 fields. Use when users say "migrate my labels to issue fields", "migrate project fields to issue fields", "convert labels to issue fields", "copy project field values to issue fields", or ask about adopting issue fields. Issue fields are org-level typed metadata (single select, text, number, date) that replace label-based workarounds with structured, searchable, cross-repo fields. | `references/issue-fields-api.md`
`references/labels-api.md`
`references/projects-api.md` | | [java-add-graalvm-native-image-support](../skills/java-add-graalvm-native-image-support/SKILL.md)
`gh skills install github/awesome-copilot java-add-graalvm-native-image-support` | GraalVM Native Image expert that adds native image support to Java applications, builds the project, analyzes build errors, applies fixes, and iterates until successful compilation using Oracle best practices. | None | diff --git a/skills/incident-postmortem/SKILL.md b/skills/incident-postmortem/SKILL.md index 1d3faf2176..383e3ad302 100644 --- a/skills/incident-postmortem/SKILL.md +++ b/skills/incident-postmortem/SKILL.md @@ -1,15 +1,17 @@ --- name: incident-postmortem -description: 'Use when an outage, production incident, or significant service degradation has occurred and the team needs to write a structured blameless post-mortem. Triggers on phrases like "write a post-mortem", "incident review", "what went wrong", "outage report", "root cause analysis", or "RCA". Covers timeline reconstruction, contributing factor analysis, impact quantification, and action item generation with owners.' +description: 'Use when an outage, production incident, or significant service degradation has occurred and the team needs a blameless post-mortem / RCA document in the Google SRE format. Triggers on phrases like "write a post-mortem", "incident review", "what went wrong", "outage report", "root cause analysis", "RCA", or "fishbone". Collects incident inputs from the user, uses a fishbone (Ishikawa) diagram to surface candidate causes, drills the strongest branches with 5 Whys, and produces typed action items. Outputs Markdown by default, with HTML, DOCX, or PDF on request.' --- -# Incident Post-Mortem +# Incident Post-Mortem (Google SRE format) -Guide a team through writing a structured, blameless post-mortem after a production incident. The output is a document that builds shared understanding, identifies root causes without blame, and produces concrete action items to prevent recurrence. +Guide a team through writing a blameless post-mortem after a production incident, following the structure of the Google SRE post-mortem template. The output builds shared understanding, identifies root causes without blame, and produces concrete action items to prevent recurrence. + +Everything in the document comes from the user. Never invent timestamps, metrics, names, or causes. If something is unknown, write it as an open question in the document. ## Blameless Principle -Systems fail, not people. The goal is to understand HOW the incident happened — not WHO caused it. Avoid language like "X forgot to", "Y should have known". Use "the system did not", "the process lacked", "the alert did not fire". +Systems fail, not people. The goal is to understand HOW the incident happened, not WHO caused it. Avoid language like "X forgot to" or "Y should have known". Use "the system did not", "the process lacked", "the alert did not fire". ## When to Use @@ -22,183 +24,140 @@ Systems fail, not people. The goal is to understand HOW the incident happened ## Input Requirements -Gather these details before writing the post-mortem. Ask for anything missing: +Gather these from the user before writing. Ask for anything missing, section by section, and do not start the analysis until the first three groups are covered. ### Incident Metadata - Incident title (short, descriptive) -- Date and time of detection (with timezone) -- Date and time of resolution -- Severity / impact level (P1–P4 or equivalent) -- Incident commander / on-call owner +- Authors / post-mortem owner, and incident commander or on-call owner +- Date and time of start, detection, and resolution (with timezone) +- Severity / impact level (P1-P4 or equivalent) ### Impact - Affected services and systems - User-facing impact (errors, slowness, full outage) -- Estimated number of users affected +- Estimated number or percentage of users affected - Data loss or corruption (yes/no, scope) -- SLA/SLO breach (yes/no, by how much) +- SLA/SLO breach (yes/no, by how much), revenue or business impact if known ### Timeline Events -Key moments to reconstruct: - First symptom occurred -- Alert fired (or was noticed manually) +- Trigger (the change or event that set the failure off, e.g. a deploy or config push) +- Alert fired, or the problem was noticed manually, and by whom - On-call paged / incident declared -- Investigation started -- Root cause identified -- Mitigation applied -- Full resolution confirmed +- Investigation started, root cause identified +- Mitigation applied, full resolution confirmed - Customer communication sent (if any) -### Contributing Factors -Ask the team: "What made this worse than it needed to be?" — not "who failed". Examples: -- Alert threshold too high / alert didn't fire -- Runbook was missing or outdated -- Deploy lacked a feature flag for rollback -- Monitoring didn't cover this failure mode -- On-call handoff missed context +### Evidence and Context +- Logs, dashboards, alerts, chat threads, or tickets to cite +- Recent changes (deploys, config, infra, dependency upgrades) +- Prior similar incidents + +### Output Format +Ask which format they want. Default to Markdown. ## Process -### Step 1 — Gather Metadata -If the user has not provided full incident details, ask for them section by section. Don't proceed to writing until you have: title, times, severity, affected services, and at least a rough timeline. +### Step 1 - Gather Inputs +Collect the inputs above. If the user pastes raw material (chat export, alert log), extract what you can and list what is still missing. + +### Step 2 - Reconstruct Timeline +Build a chronological timeline in UTC. For each event record the time, what happened (system event or human action), who observed or acted, and a link to evidence. + +Flag gaps: "We don't know what happened between 14:32 and 14:47 - worth checking logs." Separate **time to detect** (start to detection) from **time to mitigate** (detection to mitigation). + +### Step 3 - Fishbone: Brainstorm Candidate Causes +Before any 5 Whys, widen the search with a fishbone (Ishikawa) diagram. The problem statement is the "head" (the observed failure, e.g. "Checkout API returned 500s for 47 minutes"). Ask the user, for each category, "what in this area could have contributed?": -### Step 2 — Reconstruct Timeline -Work with the user to build a precise chronological timeline. For each event: -- Exact time (UTC preferred) -- What happened (system event or human action) -- Who observed it or took the action -- Link to log / alert / Slack message if available +| Category | Prompts | +|----------|---------| +| Code & Change | Recent deploy, feature flag, migration, dependency bump, missing rollback path | +| Infrastructure & Platform | Capacity, limits/quotas, autoscaling, networking, node or zone health | +| Configuration & Data | Config drift, secrets/certs expiry, data shape or volume, schema | +| Monitoring & Detection | Missing metric, alert threshold or routing, dashboard gaps, noisy alerts | +| Process & Tooling | Review/testing gaps, deploy checklist, runbooks, on-call handoff, escalation | +| Dependencies & External | Upstream/downstream services, third-party vendors, traffic spikes | -Flag gaps: "We don't know what happened between 14:32 and 14:47 — worth checking logs." +Rules: +- Collect causes from the user's evidence; propose prompts, not conclusions. Mark each cause **confirmed** (evidence exists), **suspected**, or **ruled out**. +- Leave a category empty if nothing applies. Do not pad it. +- Sub-causes may nest one level (a cause of a cause) as a branch on the bone. -### Step 3 — Root Cause Analysis -Use the **5 Whys** iteratively: +Render the result as an indented tree plus a table. See [references/fishbone-example.md](references/fishbone-example.md) for the exact shape. + +### Step 4 - 5 Whys on the Strongest Branches +Select the confirmed branches that most plausibly explain the incident (usually one to three, including at least one from Monitoring & Detection if detection was slow). Run a separate 5 Whys chain down each: ``` Why did users see 500 errors? -→ The API pods were crash-looping. - +-> The API pods were crash-looping. Why were they crash-looping? -→ Memory limit was exceeded. - +-> Memory limit was exceeded. Why was the limit exceeded? -→ A new query was loading full result sets into memory. - +-> A new query was loading full result sets into memory. Why wasn't this caught before deploy? -→ Load tests only covered the p50 case, not high-cardinality accounts. - +-> Load tests only covered the p50 case, not high-cardinality accounts. Why did load tests only cover p50? -→ We had no test fixtures for large accounts. +-> We had no test fixtures for large accounts. ``` -Stop when you reach a system/process gap you can fix. The last "why" should point to an action item. - -Distinguish: -- **Root cause** — the deepest systemic gap (one or two) -- **Contributing factors** — conditions that made it worse but aren't the root cause - -### Step 4 — Impact Quantification -Help the user be precise: -- Duration: detection to resolution (not symptom start to resolution — separate these) -- Error rate at peak vs. normal baseline -- Percentage of traffic affected -- Revenue / business impact if known - -### Step 5 — Action Items -For each root cause and contributing factor, generate at least one action item: +Guidance: +- Five is a guide. Stop when the last "why" lands on a system or process gap that can be fixed. +- "Human error" is never a stopping point; keep asking why the system allowed it. +- Each chain ends in a root cause. Record which fishbone category it came from. +- Distinguish **root causes** (deepest fixable gaps), the **trigger** (what set it off), and **contributing factors** (conditions that made it worse). Unlike a single linear chain, this approach can legitimately yield more than one root cause. -| # | Action | Owner | Due Date | Priority | -|---|--------|-------|----------|----------| -| 1 | Add load test fixtures for accounts > 10k records | @eng-team | 2026-07-01 | High | -| 2 | Lower memory alert threshold from 90% to 75% | @platform | 2026-06-23 | High | -| 3 | Add runbook for memory OOM pods | @on-call-rotation | 2026-06-30 | Medium | +### Step 5 - Impact Quantification +Help the user be precise: duration (separate detection from resolution), error rate at peak vs. baseline, percentage of traffic affected, SLO error budget consumed, revenue or business impact. -Action items must have an owner (a person, not a team) and a due date. Vague actions like "improve monitoring" are not acceptable — break them into specific deliverables. +### Step 6 - Action Items +Every root cause and contributing factor needs at least one action item. Following the Google SRE template, give each a **type**: -### Step 6 — Write the Document -Produce the full post-mortem using the template below. Save to `docs/postmortems/YYYY-MM-DD-.md`. +- **Detect** - would have alerted us sooner +- **Mitigate** - would have reduced impact or time to recover +- **Prevent** - would have stopped it from happening -## Output Template - -```markdown -# Post-Mortem: [Incident Title] - -**Date:** YYYY-MM-DD -**Severity:** P[1-4] -**Duration:** X hours Y minutes (HH:MM UTC – HH:MM UTC) -**Incident Commander:** @name -**Status:** Resolved - ---- +| # | Action | Type | Owner | Tracking | Due | Priority | +|---|--------|------|-------|----------|-----|----------| +| 1 | Add load-test fixtures for accounts > 10k records | Prevent | @person | PROJ-123 | 2026-07-01 | High | -## Summary +Include at least one Detect or Mitigate item when detection or recovery was slow, not only Prevent items. Owners are individuals, not teams. Vague actions like "improve monitoring" must be broken into specific deliverables (service, metric, threshold). Ask the user for the tracking ticket; leave it as `TBD` rather than inventing one. -[2–3 sentences. What happened, what was the user impact, how was it resolved. Written for someone who wasn't involved.] +### Step 7 - Write the Document +Fill in the template in [references/postmortem-template.md](references/postmortem-template.md). Sections follow the Google SRE order: Summary, Impact, Root Causes, Trigger, Detection, Resolution, Action Items, Lessons Learned (what went well, what went wrong, where we got lucky), Timeline, Supporting Information. The fishbone and 5 Whys go in Root Cause Analysis. -## Impact +Save Markdown to `docs/postmortems/YYYY-MM-DD-.md` unless the user names a different location. -| Dimension | Value | -|-----------|-------| -| Affected services | [list] | -| User-facing impact | [errors / degraded / full outage] | -| Users affected | [estimated number or %] | -| Peak error rate | [X% vs Y% baseline] | -| Data loss | [none / describe scope] | -| SLA breach | [yes/no — by how much] | +### Step 8 - Other Output Formats +Always produce the Markdown source first, then convert only if the user asked. -## Timeline +| Format | How | +|--------|-----| +| Markdown (default) | The `.md` file from Step 7 | +| HTML | Write a single self-contained `.html` (inline CSS, no external assets) with the same sections and tables; render the fishbone tree in a `
` block |
+| DOCX | Use the repo's `md-to-docx` skill: `node skills/md-to-docx/scripts/md-to-docx.mjs  ` (needs `npm install` in that skill's `scripts/` folder once) |
+| PDF | Print the HTML to PDF with a browser, or use a locally available tool such as Pandoc. Check what is installed and tell the user if nothing suitable is available rather than installing anything silently |
 
-All times UTC.
-
-| Time | Event |
-|------|-------|
-| HH:MM | [First symptom / alert fired] |
-| HH:MM | [On-call paged] |
-| HH:MM | [Incident declared] |
-| HH:MM | [Root cause identified] |
-| HH:MM | [Mitigation applied] |
-| HH:MM | [Full resolution confirmed] |
-| HH:MM | [Customer communication sent] |
-
-## Root Cause
-
-[1–2 paragraphs. The deepest systemic gap that, if fixed, would have prevented the incident. Written in blameless language. Reference the 5 Whys chain if helpful.]
-
-## Contributing Factors
-
-- [Factor 1 — condition that made the incident worse]
-- [Factor 2]
-- [Factor 3]
-
-## What Went Well
-
-- [Thing that worked — good alert, fast response, clear runbook]
-- [Another positive]
-
-## What Could Have Gone Better
-
-- [Gap in process, tooling, or coverage — no blame language]
-- [Another gap]
-
-## Action Items
-
-| # | Action | Owner | Due Date | Priority |
-|---|--------|-------|----------|----------|
-| 1 | [Specific deliverable] | @person | YYYY-MM-DD | High/Medium/Low |
-| 2 | | | | |
-
-## Lessons Learned
-
-[Optional. 2–4 bullet points capturing non-obvious insights worth sharing with the broader team.]
-```
+Confirm the output path(s) to the user at the end.
 
 ## Common Mistakes
 
 | Mistake | Fix |
 |---------|-----|
 | "Bob forgot to check the config" | "The deploy checklist did not include config validation" |
-| Root cause is "human error" | Keep asking Why — human error is always a symptom |
+| Root cause is "human error" | Keep asking Why - human error is always a symptom |
+| Jumping straight to one 5 Whys chain | Fishbone first, then drill the strongest branches |
+| Listing every fishbone idea as a root cause | Only evidence-backed causes get a 5 Whys chain; label the rest suspected or ruled out |
+| Only Prevent action items | Add Detect and Mitigate items too |
 | Action items without owners | Every item needs a named individual, not a team |
-| Timeline reconstructed from memory | Check logs, alerts, Slack, PagerDuty before writing |
-| "Improve monitoring" as an action | Specify: which service, which metric, what threshold, by when |
-| Post-mortem written weeks later | Write within 48–72 hours while context is fresh |
+| Timeline reconstructed from memory | Check logs, alerts, chat, and paging history before writing |
+| "Improve monitoring" as an action | Specify which service, metric, threshold, and date |
+| Post-mortem written weeks later | Write within 48-72 hours while context is fresh |
+| Filling gaps with plausible-sounding details | Mark unknowns as open questions |
+
+## Bundled Files
+
+| File | Purpose |
+|------|---------|
+| [references/postmortem-template.md](references/postmortem-template.md) | Google SRE-style post-mortem template to fill in |
+| [references/fishbone-example.md](references/fishbone-example.md) | Worked fishbone + 5 Whys example and rendering format |
diff --git a/skills/incident-postmortem/references/fishbone-example.md b/skills/incident-postmortem/references/fishbone-example.md
new file mode 100644
index 0000000000..bf0a5c5a0c
--- /dev/null
+++ b/skills/incident-postmortem/references/fishbone-example.md
@@ -0,0 +1,81 @@
+# Fishbone + 5 Whys Worked Example
+
+Illustrative data only. Use the incident details the user provides, never this content.
+
+## Problem statement (fishbone head)
+
+Checkout API returned HTTP 500 for 47 minutes for accounts with more than 10k orders.
+
+## Fishbone as an indented tree
+
+```
+Checkout API returned HTTP 500 for 47 minutes
+|
++-- Code & Change
+|   +-- [confirmed] v2.14.1 loads full result sets into memory
+|   +-- [confirmed] No feature flag, so rollback required a redeploy
++-- Infrastructure & Platform
+|   +-- [confirmed] Pod memory limit 512Mi, no headroom for large accounts
+|   +-- [ruled out] Node pressure (nodes healthy in dashboards)
++-- Configuration & Data
+|   +-- [suspected] A few accounts hold 10x the typical order count
++-- Monitoring & Detection
+|   +-- [confirmed] Memory alert threshold at 90%, pods crashed before it fired
+|   +-- [confirmed] No alert on pod restart rate
++-- Process & Tooling
+|   +-- [confirmed] Load tests cover only the p50 account size
+|   +-- [confirmed] No runbook for OOM-killed pods
++-- Dependencies & External
+    +-- [ruled out] Payment provider latency normal
+```
+
+## Fishbone as a table
+
+| Category | Cause | Status | Evidence |
+|----------|-------|--------|----------|
+| Code & Change | v2.14.1 loads full result sets into memory | Confirmed | PR link, heap profile |
+| Code & Change | No feature flag for the new query | Confirmed | Deploy config |
+| Infrastructure & Platform | 512Mi memory limit without headroom | Confirmed | Pod spec, OOMKilled events |
+| Infrastructure & Platform | Node pressure | Ruled out | Node dashboards |
+| Configuration & Data | A few accounts hold 10x the typical order count | Suspected | Needs a data query |
+| Monitoring & Detection | Memory alert at 90% never fired before crash | Confirmed | Alert history |
+| Monitoring & Detection | No alert on pod restart rate | Confirmed | Alert rule inventory |
+| Process & Tooling | Load tests cover only p50 account size | Confirmed | Test suite |
+| Process & Tooling | No OOM runbook | Confirmed | Runbook index |
+| Dependencies & External | Payment provider latency | Ruled out | Provider status page |
+
+## Selecting branches for 5 Whys
+
+Drill the confirmed branches that best explain the impact and the duration:
+
+1. **Code & Change -> Process & Tooling**: why the bad query reached production (explains the trigger).
+2. **Monitoring & Detection**: why it took 31 minutes to notice (explains the duration).
+
+## Chain 1: query reached production (categories: Code & Change, Process & Tooling)
+
+1. Why did users see 500s? -> API pods were crash-looping.
+2. Why were they crash-looping? -> Memory limit exceeded (OOMKilled).
+3. Why was the limit exceeded? -> The new query loaded full result sets into memory.
+4. Why was this not caught before deploy? -> Load tests only covered the p50 account size.
+5. Why did load tests only cover p50? -> No fixtures exist for large accounts, and nothing in the release checklist requires them.
+
+**Root cause 1:** the release process has no required test coverage for high-cardinality accounts.
+
+## Chain 2: slow detection (category: Monitoring & Detection)
+
+1. Why did it take 31 minutes to notice? -> No alert fired until customers reported errors.
+2. Why did no alert fire? -> The memory alert threshold was 90%, and pods were killed before sustained readings reached it.
+3. Why was the threshold set that way? -> It was copied from a service with a different memory profile.
+4. Why was it never revisited? -> Alert thresholds have no review owner or cadence.
+5. Why is there no owner or cadence? -> The alerting standard does not require one.
+
+**Root cause 2:** alert definitions have no ownership or periodic review, and pod restart rate is not monitored.
+
+## Resulting action items (typed)
+
+| # | Action | Type | Owner |
+|---|--------|------|-------|
+| 1 | Add load-test fixtures for accounts > 10k orders and require them in the release checklist | Prevent | @person |
+| 2 | Add an alert on pod restart rate > 3 in 5 min for the checkout service | Detect | @person |
+| 3 | Put the new query behind a feature flag with documented rollback | Mitigate | @person |
+| 4 | Write an OOM-killed-pod runbook and link it from the alert | Mitigate | @person |
diff --git a/skills/incident-postmortem/references/postmortem-template.md b/skills/incident-postmortem/references/postmortem-template.md
new file mode 100644
index 0000000000..428056baef
--- /dev/null
+++ b/skills/incident-postmortem/references/postmortem-template.md
@@ -0,0 +1,121 @@
+# Post-Mortem Template (Google SRE format)
+
+Copy this structure for the final document. Replace every bracketed placeholder with information supplied by the user. Mark anything unknown as `Open question: ...` instead of guessing.
+
+```markdown
+# Post-Mortem: [Incident Title]
+
+| | |
+|---|---|
+| **Date** | YYYY-MM-DD |
+| **Authors** | @name, @name |
+| **Status** | Draft / In review / Final |
+| **Severity** | P[1-4] |
+| **Incident commander** | @name |
+
+## Summary
+
+[2-3 sentences. What happened, the user impact, and how it was resolved. Written for someone who was not involved.]
+
+## Impact
+
+| Dimension | Value |
+|-----------|-------|
+| Affected services | [list] |
+| User-facing impact | [errors / degraded / full outage] |
+| Users affected | [number or %] |
+| Peak error rate | [X% vs Y% baseline] |
+| Data loss | [none / scope] |
+| SLO / SLA | [error budget consumed, breach yes/no] |
+| Business impact | [if known] |
+
+## Root Causes
+
+[One short paragraph per root cause, in blameless language. Each corresponds to a 5 Whys chain below.]
+
+1. **[Root cause 1]** - [one sentence]
+2. **[Root cause 2]** - [if applicable]
+
+## Trigger
+
+[The specific change or event that set the failure in motion, e.g. "Deploy of v2.14.1 at 14:02 UTC enabled the new report query".]
+
+## Detection
+
+[How the incident was detected (alert, customer report, manual). Time from start to detection. What would have detected it sooner.]
+
+## Resolution
+
+[What was done to mitigate and fully resolve. Time from detection to mitigation and to full resolution.]
+
+## Root Cause Analysis
+
+### Problem statement
+
+[The "head" of the fishbone: the observed failure in one line.]
+
+### Fishbone (candidate causes)
+
+[Indented tree, see fishbone-example.md. Mark each cause confirmed / suspected / ruled out.]
+
+| Category | Cause | Status | Evidence |
+|----------|-------|--------|----------|
+| [category] | [cause] | Confirmed / Suspected / Ruled out | [link or note] |
+
+### 5 Whys
+
+#### Chain 1: [branch name] (category: [category])
+
+1. Why [problem]? -> [answer]
+2. Why [answer]? -> [answer]
+3. Why ...? -> [answer]
+4. Why ...? -> [answer]
+5. Why ...? -> [systemic gap that can be fixed]
+
+#### Chain 2: [branch name] (category: [category])
+
+[...]
+
+### Contributing factors
+
+- [Condition that made the incident worse but is not a root cause]
+
+## Action Items
+
+| # | Action | Type (Detect / Mitigate / Prevent) | Owner | Tracking | Due | Priority |
+|---|--------|------------------------------------|-------|----------|-----|----------|
+| 1 | [Specific deliverable] | Prevent | @person | PROJ-123 or TBD | YYYY-MM-DD | High |
+
+## Lessons Learned
+
+### What went well
+
+- [Good alert, fast response, clear runbook]
+
+### What went wrong
+
+- [Gap in process, tooling, or coverage, no blame language]
+
+### Where we got lucky
+
+- [Things that limited the impact by chance rather than design]
+
+## Timeline
+
+All times UTC.
+
+| Time | Event | Source |
+|------|-------|--------|
+| HH:MM | [First symptom] | [link] |
+| HH:MM | [Trigger] | [link] |
+| HH:MM | [Alert fired / noticed] | [link] |
+| HH:MM | [On-call paged, incident declared] | [link] |
+| HH:MM | [Root cause identified] | [link] |
+| HH:MM | [Mitigation applied] | [link] |
+| HH:MM | [Full resolution confirmed] | [link] |
+| HH:MM | [Customer communication sent] | [link] |
+
+## Supporting Information
+
+- [Dashboards, logs, chat threads, tickets, related post-mortems]
+```