Skip to content
Skills Library
Programming · Review & audit

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.

Licence
MIT
Last repository change
01.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
9
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 01.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

  1. When to Use
  2. Investigation Types
  3. Core Process
  4. Output Format
Original SKILL.md headings · 116 lines, 784 words
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

RepositoryScoreLicence
This page · rileyhilliard/claude-essentials100MIT
digital-stoic-org/agent-skills100MIT
alirezarezvani/claude-skills100MIT
borghei/Claude-Skills100MIT
evanbaker315/attentionos100MIT
hanamizuki/solopreneur100MIT
bestagentkits/agency-skills100MIT

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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.