post-mortem
/post-mortem
Reviews a completed session, or many sessions, to find what caused friction and turns each finding into a concrete change with a file path (docs, CLAUDE.md, skills, hooks, tests, architecture). Use when the user asks for a post-mortem, retro, or lessons learned, asks what went wrong or what keeps going wrong in a repo, or wants to improve their Claude setup from how a session went.
- Author
- rileyhilliard ↗
- Repository
- claude-essentials ↗
- Licence
- MIT
- Last repository change
- 01.11.2026
Assessment and security
- Files in this package
- 9
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 01.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/extract-friction.py
What it does and when to use it
Reviews a completed session, or many sessions, to find what caused friction and turns each finding into a concrete change with a file path (docs, CLAUDE.md, skills, hooks, tests, architecture). Use when the user asks for a post-mortem, retro, or lessons learned, asks what went wrong or what keeps going wrong in a repo, or wants to improve their Claude setup from how a session went.
Original author description
Reviews a completed session, or many sessions, to find what caused friction and turns each finding into a concrete change with a file path (docs, CLAUDE.md, skills, hooks, tests, architecture). Use when the user asks for a post-mortem, retro, or lessons learned, asks what went wrong or what keeps going wrong in a repo, or wants to improve their Claude setup from how a session went.
How it works
- When to Use
- Investigation Types
- Core Process
- Output Format
SKILL.md preview
---
name: post-mortem
description: Reviews a completed session, or many sessions, to find what caused friction and turns each finding into a concrete change with a file path (docs, CLAUDE.md, skills, hooks, tests, architecture). Use when the user asks for a post-mortem, retro, or lessons learned, asks what went wrong or what keeps going wrong in a repo, or wants to improve their Claude setup from how a session went.
---
# Post-Mortem
Review a completed session or task to assess how it went and extract improvements. This covers both "how did we do" evaluation and "what can we learn" investigation.
## When to Use
After completing any non-trivial task or session. The goal is continuous improvement:
- **Routine review**: How smooth was execution? Where did friction occur?
- **Problem sessions**: Things took longer than expected, multiple corrections needed
- **Bug fixes**: What caused it and what would prevent it next time?
- **New patterns**: Something worked well that should be codified
## Investigation Types
Load the relevant reference based on what you're investigating:
| Situation | Load | File |
|-----------|------|------|
| Agent hit friction during execution (wrong files, bad assumptions, unclear conventions) | **DX Friction** | `references/dx-friction.md` |
| Documentation (READMEs, comments, API docs) was wrong, incomplete, or misleading | **Documentation Gaps** | `references/documentation-gaps.md` |
| Code was hard to understand or things were in unexpected places | **Architecture Clarity** | `references/architecture-clarity.md` |
| A bug was fixed but the root cause suggests a process gap | **Bug Prevention** | `references/bug-prevention.md` |
| Code works but diverges from best practices, idioms, or established conventions | **Anti-Patterns** | `references/anti-patterns.md` |
| Skills, hooks, commands, agents, or `.claude/` configs need updating | **Tooling Improvements** | `references/tooling-improvements.md` |
Load multiple references when the session spans investigation types.
For a review across many sessions ("what keeps going wrong in this repo?"), build a transcript digest first with `python3 ${CLAUDE_SKILL_DIR}/scripts/extract-friction.py --out <scratch dir>/friction`, then read the Multi-Session Reviews section of `references/dx-friction.md`.
## Core Process
Every post-mortem follows four steps regardless of investigation type.
### 1. Reconstruct What Happened
Walk through the session timeline. For each significant step, note:
- What was attempted
- What actually happened
- Where corrections were needed and why
- What went smoothly (worth noting what worked, not just what didn't)
Don't editorialize yet. Just document the sequence.
### 2. Assess Execution Quality
Evaluate how the session went overall:
- **Efficiency**: Did we take a direct path or wander? Where were the detours?
- **Accuracy**: Were initial approaches correct, or did we need multiple corrections?
- **Tooling fit**: Did skills, commands, and configs help or get in the way?
- **Communication**: Was intent clear between user and agent throughout?
- **Outcome**: Did we deliver what was asked for? Is it solid or just "works for now"?
Flag anything that felt harder than it should have been, even if it ultimately succeeded.
### 3. Identify Systemic Causes
For each friction point, ask: **"What would have prevented this?"**
Push past the first answer. "I should have read the file more carefully" is a symptom. "The file's name doesn't indicate what it contains" or "there's no convention documented for where this type of code lives" is a systemic cause.
**Good root causes** point to something fixable:
- A missing or misleading piece of documentation
- An architectural pattern that's inconsistent or undiscoverable
- A skill/config that gives wrong guidance
- A convention that exists but isn't written down
- A test gap that allowed a regression
- A workflow that worked well but isn't codified
**Bad root causes** are just descriptions of what went wrong:
- "I made a mistake"
- "The code was complex"
- "It took a while to figure out"
### 4. Propose Concrete Actions
Every finding should produce one of these:
- **Documentation update** - Fix incorrect docs, add missing docs, clarify ambiguous docs
- **Skill/config update** - Modify an existing skill or CLAUDE.md instruction
- **New skill/hook** - Create a new skill or hook to codify a pattern
- **Architecture improvement** - Refactor to make the system more discoverable
- **Test addition** - Add tests that would catch this class of issue
- **Codify a win** - Something that worked well should be made repeatable
Each action should have a specific file path and description of the change. Vague actions like "improve documentation" are not useful.
## Output Format
Match the length to the findings. Cover the substance without filler sections or a summary that repeats the findings.
```markdown
## Session Post-Mortem
### What Happened
[Timeline of the session with key decision points]
### Execution Assessment
- **Outcome:** [What was delivered vs what was asked]
- **Efficiency:** [Direct path or detours? Where and why?]
- **What worked well:** [Patterns, skills, or approaches worth repeating]
### Findings
#### Finding 1: [Title]
**What happened:** [The friction or issue, stated factually. 1-2 sentences]
**Root cause:** [The systemic issue underneath. 1-2 sentences]
**Action:** [Specific change with file path. 1-2 sentences]
**Priority:** [High/Medium/Low based on how often this would recur]
#### Finding 2: [Title]
...
### Summary
[1-2 sentences: biggest takeaway and what should change first]
```
Files in this package (9)
- SKILL.md 6 KB
- agents/openai.yaml 1 KB
- references/anti-patterns.md 4 KB
- references/architecture-clarity.md 2 KB
- references/bug-prevention.md 2 KB
- references/documentation-gaps.md 2 KB
- references/dx-friction.md 8 KB
- references/tooling-improvements.md 3 KB
- scripts/extract-friction.py 12 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · rileyhilliard/claude-essentials | 100 | MIT |
| digital-stoic-org/agent-skills | 100 | MIT |
| alirezarezvani/claude-skills | 100 | MIT |
| borghei/Claude-Skills | 100 | MIT |
| evanbaker315/attentionos | 100 | MIT |
| hanamizuki/solopreneur | 100 | MIT |
| bestagentkits/agency-skills | 100 | MIT |
Database snapshot: 13.11.2026 · package version 48b0fd6eaa64 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90dev-retro
AI DevKit · Run an evidence-based retrospective on finished work (feature, session, incident) and turn friction into durable fixes, automation first. Use when users ask for a retro, lessons learned, post-mortem, or "what went wrong", or when another skill offers one after a feature or fix. - 90printing-press-retro
Use when the user asks to retro, run a retrospective, file findings, or improve the Printing Press after a printed-CLI run. Trigger phrases: "retro", "retrospective", "what went wrong", "improve the press", "post-mortem", "lessons learned", "what can we improve", "file a retro",… - 100retro-marimo-pair
Session retrospective for improving marimo-pair and marimo._code_mode. Use when the user wants to analyze friction from a pairing session, identify what went wrong, and brainstorm improvements to the skill docs or the underlying API. Trigger on: "retro", "what went wrong",… - 100retro
Retrospective of a Claude Code session — reads the transcript, finds what went wrong or was missed (user corrections, rejected or failed tool calls, wasted detours, reviewer findings that were confirmed) and proposes concrete changes to memory, CLAUDE.md, skills, agents or hooks… - 90improve
Improve the user's Claude Code setup from evidence - reads recent friction (session logs, /insights report, repeated corrections) and proposes concrete edits to CLAUDE.md, skills, hooks or settings, optionally as a contribution to ALEXIS. Use when the user asks to improve their… - 90insight-retro
Post-implementation retrospective — map blast radius, audit documentation, extract skills, update KIs, document lessons learned. Trigger when the user runs /retro or asks for a "retrospective", "post-mortem", "lessons learned", or "what changed" after completing significant…