incident-postmortem-writer

Overview

Produces structured, blameless incident postmortems by gathering data from communication channels (Slack, Teams, email), alert histories, and user-provided context. Outputs a complete document with timeline, impact, root cause analysis, contributing factors, and action items ready for review and distribution.

Workflow

<Definition - Severity Levels> Classification of incident impact used to determine response urgency and postmortem depth:

• SEV1: Critical. Customer-facing outage affecting majority of users or revenue-generating systems. Requires immediate executive notification. Postmortem due within 48 hours.
• SEV2: Major. Significant degradation affecting a subset of users or a single critical service. Postmortem due within 5 business days.
• SEV3: Minor. Limited impact, workaround available. Postmortem due within 10 business days.
• SEV4: Low. Minimal user impact, detected internally. Postmortem optional but recommended for learning. </Definition - Severity Levels>

<Definition - Blameless Language> Writing that focuses on systems, processes, and conditions rather than individual fault. Instead of "Engineer X forgot to check the config," write "The deployment process did not include a config validation step." Replace personal attribution with systemic observations. Use passive voice only when it removes blame without obscuring what happened. Active voice with system subjects is preferred: "The load balancer routed traffic to the unhealthy host" rather than "Traffic was routed incorrectly." </Definition - Blameless Language>

<Definition - Five Whys> A root cause analysis technique that asks "why" iteratively (typically five times) to move from symptoms to underlying systemic causes. Each answer becomes the subject of the next "why" question. The goal is to reach a cause that, if addressed, would prevent recurrence. Stop when you reach a process, tooling, or organizational gap that is actionable. </Definition - Five Whys>

<Workflow - Incident Postmortem description="End-to-end postmortem drafting flow from data gathering through final document." tools=[file_write, file_read, run_python, open_in_session_tab] triggers=["write a postmortem", "draft incident report", "document this outage", "create a post-incident review", "RCA for the incident"]

1. [Agent] Determine today's date. Validate the provided incident_date and severity. Calculate the postmortem due date based on severity level definitions. If fails: If the incident_date or severity is invalid, report the problem and ask the user to provide a valid value before continuing.
2. [Ask user] Confirm the incident summary and gather additional context: What services were affected? Was there a deploy or change preceding the incident? What was the customer-visible impact? Who was the incident commander or on-call responder (role, not for blame, but for sourcing information)? If fails: If the incident context is not provided, re-ask for the affected services and customer-visible impact before proceeding.
3. [Decide] Is a communication channel or data source provided?
   • Yes: Proceed to step 4.
   • No: Ask the user if there is a relevant channel, alert log, or other timeline source. If none, proceed to step 5 using only the verbal debrief.
4. [Agent] Retrieve messages from the incident communication channel for the incident date. Extract messages that contain: alerts firing, status changes, actions taken, hypotheses discussed, and resolution confirmation. Process in chronological order. If the channel has more messages than a single retrieval allows, paginate and stitch together. If fails: If the channel messages cannot be retrieved, note the gap in the timeline source and proceed with the user-provided context and any other available data.
5. [Think] From all available data (channel messages, user-provided context, alert data), construct a draft timeline. For each entry, record: timestamp (normalized to a single timezone), what happened, and the source of that information. Identify gaps where no data exists between known events.
6. [Ask user] Present the draft timeline. Ask: Are there missing events? Are any timestamps wrong? Were there other channels or data sources with relevant information? Is the timezone correct? If fails: If the user does not respond, re-present the draft timeline and ask specifically about missing events, timestamps, and timezone.
7. [Think] Analyze the timeline to identify root cause and contributing factors. Apply the Five Whys technique starting from the customer-visible symptom. Separate the trigger (what initiated the failure) from contributing factors (what made it worse or prevented faster detection/resolution). Label anything uncertain as a hypothesis.
8. [Ask user] Present the root cause analysis and contributing factors. Ask: Does this match the team's understanding? Are there additional contributing factors? Should any hypothesis be promoted to confirmed or removed? If fails: If the user does not confirm the analysis, re-present it and ask which factors to add, remove, or promote from hypothesis.
9. [Agent] Draft the full postmortem document using the Postmortem Template. Populate all sections from gathered data. Ensure blameless language throughout. Generate action items based on: gaps in detection (monitoring), gaps in prevention (testing, validation), gaps in response (runbooks, tooling), and gaps in communication (status pages, stakeholder notification). If fails: If the document cannot be drafted, report the error and present the gathered sections inline so no data is lost.
10. [Ask user] Present the complete draft. Ask for revisions: Are action items correct and assigned to the right teams? Is the impact assessment accurate? Should any section be expanded or reduced? Iterate until the user approves. If fails: If the user does not approve or request specific revisions, re-present the draft and ask what needs to change before finalizing.
11. [Agent] Save the final postmortem to the workspace as a Markdown file. Name it: postmortem-{{incident_date}}-<slug>.md where <slug> is a short slug derived from the incident summary. Open it in the session tab for review. If fails: If the postmortem cannot be saved or opened, report the error, retry once, and present the document inline if the retry fails.

</Workflow - Incident Postmortem>

<Template - Postmortem>

# Incident Postmortem: {{incident_summary}}

**Date:** {{incident_date}}
**Severity:** {{severity}}
**Author:** {{author}}
**Status:** Draft / Final
**Postmortem Due:** {{due_date}}

---

## Summary

A 2-3 sentence overview of what happened, how long it lasted, and the customer impact.

---

## Timeline

All times in {{timezone}}.

| Time | Event | Source |
|------|-------|--------|
| HH:MM | First alert fired | PagerDuty / CloudWatch |
| HH:MM | Incident channel created | Chat platform |
| HH:MM | Root cause identified | Chat platform |
| HH:MM | Fix deployed | Chat / CI |
| HH:MM | Service fully recovered | Monitoring |

---

## Impact

- **Duration:** X minutes / hours
- **Users affected:** Number or percentage
- **Requests affected:** Error count or error rate
- **Revenue impact:** Estimated if known, otherwise "Not quantified"
- **SLA/SLO breach:** Yes / No (specify which)

---

## Root Cause

A clear, blameless explanation of why the incident occurred. Focus on the systemic failure, not individual actions.

### Five Whys

1. Why did customers see errors? Because...
2. Why did that happen? Because...
3. Why did that happen? Because...
4. Why did that happen? Because...
5. Why did that happen? Because...

---

## Contributing Factors

Conditions that did not directly cause the incident but made it more likely, more severe, or harder to resolve:

- Factor 1
- Factor 2
- Factor 3

---

## Detection

How was the incident detected? How long between start of impact and detection? What could have detected it sooner?

---

## Response

What went well in the response? What was difficult or slow? Were runbooks available and accurate?

---

## Action Items

| ID | Action | Owner (Team) | Priority | Due Date | Status |
|----|--------|--------------|----------|----------|--------|
| 1 | Specific, verifiable action | Team name | P1/P2/P3 | YYYY-MM-DD | Open |
| 2 | Specific, verifiable action | Team name | P1/P2/P3 | YYYY-MM-DD | Open |

---

## Lessons Learned

### What went well
- Item

### What could be improved
- Item

### Where we got lucky
- Item

</Template - Postmortem>