retro

retro — session retrospectives for Claude Code

LLM-driven session retrospection for Claude Code agents. After a session, /retro reads the conversation transcript, detects friction, and routes each finding to one of six homes — with per-proposal approval and no silent writes.

Where continuous friction-detection hooks pile up write-only noise nobody triages, /retro reads what actually happened and hands you a short list of approved, durable learnings — global memory, project rules, or skill PRs.

Contents

• What it does
• Why
• Requirements
• Install
• Usage — the four modes
• A worked example
• The six destinations
• How it works
• How it stays safe
• Honest limitations
• Optional auto-trigger
• Repository layout
• Related projects
• Contributing
• License

What it does

/retro analyzes the current Claude Code session directly from the conversation transcript — no continuous background hooks. It detects friction (tool errors, repeated mistakes, skills that should have triggered but didn't, convention violations), classifies each finding into exactly one of six destinations, and materializes the approved learnings. Every write is gated behind explicit per-proposal approval.

A single sweep returns at most ten actionable proposals, grouped by destination, each with a short why and a how-to-apply.

Why

The prior approach — the Coach plugin — used continuous friction-detection hooks that turned out to be write-only noise. The field evidence was stark:

• ~/.claude-coach/candidates.json held 1011 pending / 0 approved / 0 rejected.
• A 35 MB events.sqlite produced roughly 35× duplicate fingerprints of the same issue.

An LLM reading the actual transcript classifies friction more accurately and far more cheaply, and returns ≤10 actionable proposals instead of 1011 candidates nobody triages. That is the entire premise of /retro: one efficient pass over what really happened, not a firehose of background candidates.

Requirements

Tool	Used for
Claude Code	The host that runs the plugin and the /retro command
python3	Mechanical pre-pass and the cross-session scan
jq	Skill discovery, manifest parsing, and the optional hook
gh and/or glab	Creating pull/merge requests for skill updates
git	Cloning source repos and materializing changes

Install

/retro ships as a Claude Code plugin. A bare single-plugin repo can be added to the marketplace directly — no marketplace.json required. Run both steps inside Claude Code:

/plugin marketplace add netresearch/retro-skill
/plugin install retro@netresearch/retro-skill

Alternatively, install via Composer (the skill-repo convention):

composer require netresearch/retro-skill

Usage — the four modes

Command	Mode	When to use
/retro	Sweep — analyze the entire current session; returns ≤10 proposals grouped by destination	At session end, or when friction has accumulated
/retro "<problem>"	Spotlight — focus on one described issue; fewer tokens than a full sweep	Mid-session, for a direct fix
/retro outcome [session-id|--since N]	Outcome (layer D) — replay a past session through what happened to its output afterwards (reverted commits, rejected PRs, CI failures, follow-up fix sessions)	Periodically, e.g. monthly. Do not run within 24h of the session — the outcomes have not landed yet
/retro audit [--scope project|repo|skill]	Constitutional audit — cross-session architectural review (design drift, convention erosion) over weeks/months	Monthly or quarterly health check
/retro promote	Promote — inventory accumulated project-local memory (all slugs) and re-home each note upward (skill-update › project-rule › user-memory; never project-local memory), draining the source only after the upward write is verified	When local memory has piled up and you want it shared and emptied

Sweep and Spotlight answer "what went wrong this session?". Outcome and Audit answer "did our past decisions survive contact with reality?" and "is the system still on track?" — friction that does not show up inside a single session.

A worked example