# Post Mortem > Use this skill when the user asks to write a post-mortem, run a retrospective on a shipped or failed project, analyze an incident, or capture lessons from a near-miss. Trigger phrases include "write the post-mortem", "run the retro", "debrief this incident", "what went wrong", "post-mortem de este incidente", "retro del proyecto", "lessons learned", "blameless retro". Produces a timeline of facts, contributing factors, action items with owners, and structural signals, without blaming individuals. - Skill: `federicoimparatta/post-mortem` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add federicoimparatta/post-mortem` - Raw SKILL.md: https://api.skillmd.com/api/skills/federicoimparatta/post-mortem/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: federicoimparatta (https://skillmd.com/u/federicoimparatta) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/federicoimparatta/post-mortem --- # post-mortem > **Anchor:** A post-mortem is a tool for the next incident, not a trial for the last one. ## When to use Use this skill when the user needs a structured retrospective on something that has already happened. Works for: - An outage, security incident, or production bug with customer impact. - A launch that failed to move the intended metric. - A project that shipped late, over budget, or with features cut. - A near-miss where the wrong outcome was avoided but barely. - A recurring pattern of small failures that suggests a structural issue. Do not use when: - The user is red-teaming a plan before it executes. Use `red-team-review`. - The user is evaluating a candidate after a failed hire. Use `candidate-evaluation`. - The user is writing a scorecard for an ongoing vendor. Use `vendor-evaluation`. ## Philosophy A post-mortem is a ritual, and rituals serve results. Three handbook concepts apply. **No heroes, no blame:** blaming individuals makes the next post-mortem harder to write honestly, and hides the structural conditions that produced the failure. The goal is to change the conditions, not to name a villain. **Rituals serve results:** a retro that follows the template but produces no change in how the team operates next time has failed. Every post-mortem closes with things that will be different, owned, and scheduled. **Cultural signals are delivery:** how the retro is run is itself the signal. A team that cannot hold a blameless conversation about a failure will deliver differently than one that can. ## Voice rules (apply to all outputs) - No buzzwords: leverage, empower, synergy, resonate, tapestry, delve, elevate, captivate, explore, dynamic, testament. - No em dashes. - No filler openings. - Decision-oriented over descriptive. - High-context, no overexplaining. - Standard sentence case for formal outputs. - ES outputs match the register of the handbook: direct, self-aware, no reverence for process, comfortable naming failure. - EN outputs use direct US business register. Do not soften bluntness into corporate-speak. - Language switches based on audience, not author. ## Bilingual handling - **ES.** Rioplatense register. Vos over tú. Keep standard terms in English: post-mortem, incident, blameless, timeline, contributing factor, action item, owner, retro, near-miss, runbook, SEV-1, SEV-2, detection, recovery, rollback, comms, customer impact. - **EN.** Direct US business register. Do not soften failure language. - Names of services, systems, and environments stay as they are in the org. ## Method ### Step 1. Scope the retrospective A vague scope produces a vague retro. Write: - **What happened.** One paragraph in plain language, no jargon. - **When.** Start and end timestamps with timezone, or date range for a project. - **Who was affected.** Customers, internal users, partners, regulators. Numbers if available. - **Severity.** If this is an incident, the formal severity. If a project retro, the business impact. - **Type.** Incident, launch retro, project retro, near-miss, pattern review. ### Step 2. Build the timeline from facts The timeline is the spine. It precedes analysis. Rules: - Only facts. Time-ordered. Attributed to a system log, message, or named person's report. - No interpretation yet. No "should have" or "could have". - Include detection, mitigation, escalation, and recovery markers. - Include external facts: customer tickets, press, regulator contact, if relevant. If the timeline is disputed, flag the specific entry. Do not erase it. ### Step 3. Identify contributing factors, not a single cause Failures are almost never a single cause. Write three to seven contributing factors. Each factor is: - **The condition.** A property of the system, the process, or the context. - **Why it contributed.** The specific way it made this failure more likely or worse. - **Not a name.** A factor is never "X forgot to do Y". It is "the process did not catch that Y was missing". Reframe any individual-level blame into the conditions that allowed the behavior. ### Step 4. What worked Equal weight to what worked. This section is not a performative positive; it is essential for learning. - **Detection.** Signals that fired fast and accurately. - **Response.** Behaviors during the incident that limited damage. - **Recovery.** Patterns that got the system back to green. - **Communication.** Where the team, customers, and leadership were aligned. What worked is what you want to scale. Name it with the same rigor as what did not. ### Step 5. What did not work - **Detection gaps.** What was not signaling, or signaled too late. - **Response gaps.** Where the runbook or escalation broke down. - **Recovery gaps.** Where the rollback was absent, slow, or hazardous. - **Communication gaps.** Where internal or external comms lagged or confused. - **Decision gaps.** Where a decision was hard to make because the authority or information was missing. ### Step 6. Write action items that change conditions Every contributing factor gets at least one action item, unless the team explicitly decides to accept the risk. Each action item has: - **The change.** A specific thing that will be different next time. - **Owner.** Named person, not a team. - **Due date.** Specific, not "soon". - **How we will know it landed.** The signal that confirms the action took effect. - **Kill criterion.** What would cause this action to be deprioritized or canceled. Action items without owners, dates, and verification are wishes. ### Step 7. Capture structural and cultural signals Some failures point at patterns beyond the specific incident. Call them out: - **Structural.** "The on-call rotation is thin enough that one person's sick day caused the escalation to stall." - **Cultural.** "The team did not surface concerns about this service earlier because the last time they did, the response was defensive." - **Process.** "Changes of this class have shipped without a staging test three times in the last quarter." These are for leadership to act on. Do not hide them in the body of the retro. ### Step 8. Name documentation to create or update Most retros reveal missing or wrong docs. Be specific: - **Runbook to create.** For the specific failure mode. - **Runbook to update.** What changed. - **Policy to revise.** If a policy allowed the failure. - **Architecture note.** If a design decision needs to be recorded for the next team. Link to the skills that can produce these (`documentation-extraction`). ### Step 9. Distribute and revisit A post-mortem in a drawer is worse than no post-mortem. Define: - **Audience.** Who must read this. - **Publication channel.** Where it lives. - **Revisit date.** When the team checks whether action items actually landed. - **Deprecation signal.** When the post-mortem is closed for maintenance. ## Templates - `templates/en/incident-post-mortem.md`: production incident retro. - `templates/en/project-retro.md`: project, launch, or initiative retro. - `templates/es/incident-post-mortem.md`: retro de incidente de producción. - `templates/es/project-retro.md`: retro de proyecto, lanzamiento, o iniciativa. ## Related skills - `red-team-review`: use it instead when the plan has not executed yet and you want a pre-mortem. - `candidate-evaluation`: use it when the retro is on a failed hire and the rubric needs refining. - `vendor-evaluation`: use it when scoring an ongoing vendor rather than a past incident. - `documentation-extraction`: use it to turn the retro's runbook and doc gaps into durable docs. ## Anti-patterns This skill must never produce: - A post-mortem that names an individual as the cause. - A timeline that is interpretive instead of factual. - A "single root cause" in a system that obviously had several. - Action items without owners, dates, or verification. - A retro that buries cultural or structural signals inside the body. - A retro that uses "learning opportunity" as a substitute for action. - A retro that is never revisited. - A post-mortem that quietly absolves the decision-makers who set the conditions. ## Checklist before delivery - [ ] Scope, timing, affected parties, severity, and type are named. - [ ] Timeline is facts-only, attributed, and time-ordered. - [ ] Three to seven contributing factors are written, each framed as conditions. - [ ] What worked is covered with the same rigor as what did not. - [ ] Every contributing factor has at least one action item or an explicit risk acceptance. - [ ] Every action item has owner, date, verification, and kill criterion. - [ ] Structural and cultural signals are surfaced for leadership. - [ ] Documentation to create or update is named. - [ ] Audience, channel, and revisit date are named. - [ ] No buzzwords from the voice rules appear.