after-action-report

Files (2)

• SKILL.md
• aar-template.md · references/

SKILL.md (first lines)

# After-Action Report

Run a structured retrospective on a launch, incident, or completed project. Produce actionable lessons, not just a document.

This skill is for after-the-fact analysis. For active incident response, use `incident-response`. For planning launches, use `launch-runbook`.

---

## When to use

- After any incident (any severity)
- After every major launch
- At the end of a project (sprint retro, quarterly retro, project closeout)
- When a recurring issue has happened enough times to demand investigation
- When a decision didn't work out and the team wants to learn

## When NOT to use

- During an active incident (use `incident-response`)
- For pre-launch planning (use `launch-runbook`)
- For one-off bug fixes that don't merit broad analysis

---

## Required inputs

- The event being analyzed (incident, launch, project)
- A timeline reconstructed from logs, chat, tickets
- Participant accounts of what they observed and did
- Outcomes and impact (what actually happened to users, the business)

---

## The framework: blameless analysis

The most important principle: blameless. Without it, retrospectives produce hidden information and theatrical lessons rather than real ones.

### What blameless means

- Focus on systems, not individuals
- Assume everyone made reasonable decisions given what they knew at the time
- The question is "why was this decision reasonable to make?" not "who screwed up?"
- Fixing the system means the next person in that situation succeeds where this person didn't

### What blameless does not mean

- No accountability (action items still have owners)
- No hard truths (sometimes the system is broken in obvious ways)
- No standards (some patterns of failure are individual, not systemic)
- No discomfort (real reflection is uncomfortable)

---

## The framework: 6 sections

A complete AAR covers six sections.

### 1. Summary

A 2 to 3 paragraph overview. Captures:

- What happened
- Impact (users, business, time)
- Root cause (in plain language)
- Top action items

This is what executives read. Anyone who reads only this section should leave with the most important information.

### 2. Timeline

A reconstructed timeline of events.

For incidents:
- T-0: Detection
- T+X: Acknowledgment
- T+Y: Severity assessed, IC assigned
- T+Z: Investigation began
- ... mitigation, communication, resolution events
- T+N: Resolution declared

For launches:
- Pre-launch decisions and milestones
- Launch day events
- Post-launch monitoring observations

For projects:
- Major milestones, decisions, pivots
- Both planned and emergent

The timeline is the source of truth. Disagreements about what happened get resolved here.

### 3. Root cause analysis

What caused this, in plain language.

Use one or both of:

**Five whys.** Start with the surface symptom. Ask "why?" Repeat 5 times (or until you reach a true root). Each "why" should yield a substantive answer, not a tautology.

Example:
- Why did the site go down? Database connection pool exhausted.
- Why was the pool exhausted? Background job opened too many connections.
- Why did the background job open too many connections? Connection cleanup code didn't run on errors.
- Why didn't cleanup run on errors? Original code review didn't cover error paths.
- Why didn't the review cover error paths? No checklist for error handling in our review process.

The fifth why often reveals the system fix. In this case: improve the review process.

**Causal chain.** Multiple contributing factors that combined.

- Factor 1: Background job opened too many connections (technical)
- Factor 2: Connection limit was set too low for actual traffic (configuration)
- Factor 3: No alert on connection pool saturation (monitoring)
- Factor 4: Recent traffic doubled without infra capacity review (process)

No single fix addresses the incident. Multiple gaps need attention.

### 4. Contributing factors

From rampstackco/claude-skills, MIT.

More from rampstackco/claude-skills