# Retro

> Run a structured session retrospective: extract transcript metrics, assess quality across five dimensions, check feedback-memory regressions, and codify learnings durably. Use when: 'retro', 'retrospective', 'what did we learn', 'how did I do', 'codify learnings', 'show trends', or at end of session; modes: session (default), codify, trends, quick.

- Skill: `melodic-software/retro` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add melodic-software/retro`
- Raw SKILL.md: https://api.skillmd.com/api/skills/melodic-software/retro/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: melodic-software (https://skillmd.com/u/melodic-software)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/melodic-software/retro

---


## Context. Gather first

Take `session-id`, `branch`, `status`, `recent-commits` at `-5`, and `changed-files`, the only
consumer taking that last one, since a retrospective reasons over what the session actually touched.
Probe commands, the one-command-per-call and treat-failure-as-unknown rules, and the `$`-expansion
rationale for gathering at run time rather than pre-computing:
[`${CLAUDE_PLUGIN_ROOT}/reference/gather.md`](${CLAUDE_PLUGIN_ROOT}/reference/gather.md).

## Purpose

The self-improvement loop. Answers: "What happened, what did we learn, and how do we prevent the
same mistakes next time?" Every other workflow stage is about the current task; this skill is about
the next task, and every task after that.

**Three concepts this skill enforces:**

1. **Analyze**. Examine what happened with evidence (transcript metrics, conversation context,
   feedback regressions)
2. **Identify**. Find errors, behavioral adjustments, process improvements, and skill/tool
   candidates
3. **Codify**. Persist learnings durably (the consuming repo's instruction files and rules, or
   Claude Code auto-memory for contributor-specific facts)

**What this skill is NOT:** not a code review (design judgment on current work), not outcome
verification (does the change match intent), and not Claude Code's built-in `/insights`
(cross-session usage analytics); this is structured quality analysis with codification.

## Paths

Resolve at runtime, never hardcode machine-specific paths:

- **Session data root**. `~/.claude/projects/<project-slug>/`, where `<project-slug>` is the
  project's absolute path with every character outside `[A-Za-z0-9]` replaced by `-`:

  ```bash
  PROJECT_SLUG=$(pwd -W 2>/dev/null || pwd)          # Windows drive form when available
  PROJECT_SLUG=$(printf '%s' "$PROJECT_SLUG" | sed 's/[^A-Za-z0-9]/-/g')
  SESSION_DATA_DIR="$HOME/.claude/projects/$PROJECT_SLUG"
  ```

  Verify the directory exists before use; if the computed slug misses, find it by locating the
  current session's JSONL: `ls "$HOME/.claude/projects"/*/"${CLAUDE_CODE_SESSION_ID}.jsonl"`.
- Transcript: `<SESSION_DATA_DIR>/<session-id>.jsonl`; subagents:
  `<SESSION_DATA_DIR>/<session-id>/subagents/`
- **Auto-memory** (feedback regression check): `<SESSION_DATA_DIR>/memory/`. Present only when the
  consumer uses Claude Code auto-memory; degrade gracefully when absent
- **Score history** (plugin state): `${CLAUDE_PLUGIN_DATA}/scores/<project-slug>.md`. Survives
  plugin updates, never lands in the consumer's repo
- Parser: `${CLAUDE_PLUGIN_ROOT}/skills/retro/scripts/parse_transcript.py` (stdlib-only,
  Python 3.10+)

## Step 0: Detect mode

| Signal | Mode | Context file |
|--------|------|-------------|
| End of session, bare `/session-flow:retro`, post-merge | **session** | `context/session.md`, full 5-phase analysis |
| "codify", "save learnings", mid-session learning | **codify** | `context/codify.md`, targeted codification only |
| "trends", "scores", "how am I doing" | **trends** | `context/trends.md`, cross-session score history |
| "quick retro", short session, limited context | **quick** | `context/quick.md`, abbreviated pass |

If `$ARGUMENTS` specifies a mode, use it. Otherwise infer from context; when the session is long or
degraded, or compaction has occurred, prefer `quick`; ambiguous → `session`. Read the mode's context
file before proceeding.

## Step 1: Execute the mode

Follow the selected context file. Each mode has its own phases, outputs, and interactive
checkpoints.

### Reference index. Load on demand

| File | Load when |
|---|---|
| [reference/ecosystem-improvement-catalog.md](reference/ecosystem-improvement-catalog.md) | Before filling session mode's Phase 3 recommendation table, and any other time a finding has to be mapped to an ecosystem target. It owns the project-vs-personal placement decision tree and the per-target recommendation format for memory, rules, hooks, skills, agents, MCP servers, and settings. |

## Step 2: Handoff

After the retrospective:

| Condition | Suggestion |
|-----------|-----------|
| End-of-session, retro complete | Suggest any wrap-up steps the consuming repo defines |
| Codify mode, learnings saved | Return to the task at hand |
| Trends mode, analysis presented | Suggest focus areas for next session |
| Session mode, follow-ups queued | Suggest filing them in the consumer's work-item tracker |

## Multi-session awareness

When the sibling `handoff` skill's save-points exist (the resolved `<memory_dir>/handoffs/`,
default `.work/handoffs/`; or the consuming repo's documented location), the retro spans the
whole session CHAIN, not just the current session: the
parser's `--chain-from` walks `previous_handoff` frontmatter pointers
backwards from the newest handoff file and aggregates metrics across every chained transcript. See
`context/session.md` Phase 1.

**State the discovery basis, and never present a low-coverage chain retro silently.** The walk
follows `previous_handoff` pointers, so it stops at the first session that wrote no handoff file,
a chain linked by hand-pasted continuation prompts instead of save-points can end after one hop.
The parser reports what it saw in `chain_coverage` (`requested` / `found` / `available` / `ratio`,
where `available` counts the transcripts present for this project). When `ratio` is below ~0.5, say
so before presenting: name the found and available counts, and offer `--sessions` with the ids
enumerated explicitly. A retro authored from a fifth of the evidence must not read like a complete
one.

**Offer a durable copy when the session was worth retrospecting.** The transcripts this retro reads
are retention-swept (`cleanupPeriodDays`, default 30 days), and the conversation itself has no
durable artifact; a session interesting enough to retrospect is the one worth keeping. The default
is verified 2026-09-06 against Claude Code 2.1.263 and
[Data usage](https://code.claude.com/docs/en/data-usage#data-retention), which states that clients
store session transcripts locally under `~/.claude/projects/` for 30 days by default and that
`cleanupPeriodDays` adjusts the period. Recheck when that page names a different default, or when a
release note names `cleanupPeriodDays`. When the
built-in `export` command resolves in your session, close by offering the one-line export
`/export <memory_dir>/exports/<YYYYMMDDTHHMMSSZ>-<topic>.txt`, after verifying the memory root's
self-ignore guard (a `.gitignore` containing `*`, created and announced when absent). Offer only,
never run: built-ins are user-invoked, and nothing records or verifies that the export happened.

## What this skill does NOT do

- **Does not run builds or tests**. That's the consuming repo's verify stage
- **Does not review code quality**. That's its review stage
- **Does not write scores or reports into the consumer's repo**. Plugin state stays in
  `${CLAUDE_PLUGIN_DATA}`; only user-approved codifications (rule edits, memory entries) land
  outside it
- **Does not read a consumer-supplied scoring rubric**. The five dimensions are fixed plugin
  identity, not consumer config, and there is no seam to swap them. What adapts is what each
  dimension scores *against* (your repo's conventions, session-type calibration), never the
  dimensions themselves.

## Gotchas

- **Run all phases by default** in session mode. Skip metrics only when the parser fails or the
  user asks
- **Always include skill-candidate and follow-up-candidate analysis**, even when the conclusion is
  "no candidates this session"
- **Codify follows the workflow too**. Adding a bullet to a rules file requires verification, not
  just pasting
- **Phase 4 is an interactive checkpoint**, never persist codifications without explicit user
  approval