Retro

retro — turn your agent's failures into harness improvements

You are running a retrospective on how the agent (you) has been performing for this user, based on their real session transcripts. The goal is not a report for the sake of a report. The goal is a small number of concrete, minimal changes to the harness (CLAUDE.md, skills, hooks, permissions, memory) that would have prevented the friction you find. Evidence first, changes second.

Arguments

$ARGUMENTS maps to scanner flags:

• Nd (e.g. 7d, 90d) → --days N (strip the d)
• all → --all (omit --project)
• they combine: /retro all 90d → --all --days 90
• no arguments → current project, --days 30

Step 1 — collect signals

Locate the scanner, in order: ${CLAUDE_PLUGIN_ROOT}/scripts/scan.py (set when installed as a plugin); ~/.claude/skills/retro/scripts/scan.py; if $CLAUDE_CONFIG_DIR is set, $CLAUDE_CONFIG_DIR/skills/retro/scripts/scan.py; then .claude/skills/retro/scripts/scan.py in the project. Then run it with an explicit absolute project path (do not rely on the shell's cwd):

python3 ~/.claude/skills/retro/scripts/scan.py \
  --project "" --days 30 --format json

Sanity-check the output before proceeding:

• project and sessions_scanned look right for this project.
• If the scanner exits with "no transcripts", say so and stop; offer

/retro all.

• If sessions_scanned is 0, or it is small and every totals value is 0,

do NOT write a full retro. Tell the user plainly there is not enough history here yet, suggest /retro all and /retro 90d, and stop. A hollow zeros-report reads as "broken".

• With fewer than ~3 sessions, don't hunt cross-session patterns (every

cluster field is empty by construction). Do a single-session post-mortem: the one place the agent claimed done-but-wasn't, at most one earned rule, and say explicitly this is not a trend.

• If truncated is true OR sessions_scanned equals --limit, the window

was capped: rerun with --limit 1000 before doing anything else, or state the real coverage in the report header instead of "last N days".

• Sessions are selected by file modification time; individual quotes carry

their own ts and may predate the window. Check the ts of every quote you cite; present older evidence as such, never as recent.

Step 2 — read the current harness

Read the project's CLAUDE.md (also check claude.md / Claude.md and ~/.claude/CLAUDE.md). You need it to tell which failures happened BECAUSE a rule is missing, unclear, or being ignored, versus failures no rule could have prevented.

Check the rule's age against the failures' dates before you claim "the rule was ignored". A rule that already covers a failure has three possible readings, and they lead to different fixes:

1. The rule predates the failures → it exists but the agent doesn't act on

it. Fix: harden it into a blocking gate, not a fresh rule.

1. The rule was added after the failures (often as a reaction to them) →

the failures are already addressed; do not re-report them as open.

1. No rule covered it → propose a new rule.

Compare git log -1 --format=%cI -- CLAUDE.md (or the file mtime) and, if you can, git blame the specific line against the ts of the evidence quotes. If you cannot establish the order, say so in the report rather than asserting the rule was ignored.

Note: design-heavy projects often keep CLAUDE.md gitignored. If git ls-files --error-unmatch CLAUDE.md fails, the file is untracked and git blame is unavailable — individual rule ages are unknown. Use whole-file mtime plus content match only as weak evidence, and never claim a rule was "ignored" on that basis alone.

If no project CLAUDE.md exists, the Step 4 diff becomes a proposed new file: say "create /CLAUDE.md" and show its full contents. Rules that describe the user rather than one project (reply language, tone, commit habits) belong in ~/.claude/CLAUDE.md — mark those as user-level.

Step 3 — cluster into patterns

Identify at most 5 recurring patterns. A pattern needs at least 2 independent occurrences (exception below). For each candidate, check the excerpts yourself: a "correction" flagged by the scanner may be a normal instruction — drop those.

Start with the highest-yield fields:

• rule_requests — the user dictated a rule out loud ("запомни, отныне

всегда..."). Exception to the 2-occurrence rule: one rule_request is enough — the user explicitly asked. But read the surrounding transcript before converting: reconcile with existing CLAUDE.md content (the literal words may contradict a documented legitimate case), and drop entries too vague to reconstruct.

• repeated_instructions — the same ask across 2+ sessions, with session

ids and timestamps per example. Each cluster is a candidate rule, not a rule by definition: reject clusters that are per-task go-ahead commands the user must issue deliberately (deploy, "commit this now"), and clusters already covered by CLAUDE.md — those become "rule exists but isn't followed", which is a different fix (harden the rule into a blocking gate, sharpen its wording, or move it higher in the file) — but first confirm the rule predates the failures, per Step 2, or you will re-report a fix that already landed.

• admissions — the agent conceded a mistake; user_text holds what the

user complained about, admission often names the root cause.

• error_loops — the same tool+target failing 2+ times: the source for

"wrong default in the harness" patterns (wrong test runner, missing env). retry_loops is the ≥3-failure subset.

• nudges — only per-session counts: filter sessions[] for nudges >= 2

(= the agent stalls mid-task). For quotes, grep those transcripts; otherwise cite session titles and dates from sessions[].

On design, creative, or writing projects, redo and bare comparatives ("shorter", "покороче", "мельче", "переделай хедер") are usually the WORK, not agent failure — that is just what iteration sounds like. Require an after_success_claim, frustration, failure_report, or post_interrupt co-tag before counting a redo- or correction-only entry as a pattern, or you will over-report friction on creative repos.

To form candidates from the flat corrections list: group by recurring nouns/verbs in text and by session overlap with other signals; a candidate is any theme with 2+ entries. Weigh reasons tags in this order (strongest first):

1. after_success_claim — agent said "done/fixed", user came back with a

failure. Near-certain, and the most expensive kind.

1. frustration — the user is visibly angry.
2. post_interrupt — Esc + redirect. ~70% are real.
3. failure_report — something built or claimed broke.
4. correction / redo / repeat_paste — real but noisier; verify quotes.

Multi-reason entries outrank single-reason ones. Note: the excerpt arrays are capped (corrections 80, admissions 40, sessions 100 + all abandoned) — use totals for counts, arrays for quotes. Ignore top_correction_terms unless it shows an obvious theme.

If you need more context on a session, its transcript is at ~/.claude/projects//.jsonl — grep around the relevant timestamps; transcripts are large.

Step 3.5 — fan out to subagents when the report is large

If totals.corrections + totals.admissions > 40, or you have 5+ candidate patterns, do not judge everything in this context — you will skim and miss. Spawn one verification subagent per candidate pattern (Agent/Task tool, in parallel). Give each: the pattern name, its excerpts with session ids and timestamps, the transcript directory path, and this instruction:

> Verify this candidate pattern against the raw transcripts. Return: > CONFIRMED or REJECTED, the 2 best verbatim quotes with dates, a one-line > root cause, and a proposed minimal rule. Reject if the quotes read as > normal instructions rather than friction.

Then judge the returned evidence yourself and keep at most 5 confirmed patterns. Subagents read transcripts locally; nothing leaves the machine.

Step 4 — write the retro

Present in chat, in the user's language, in this shape:

# Retro:  — 

## Pattern 1:  ( occurrences,  sessions)
Evidence: 1-3 real quotes, each dated (or "N sessions, undated" — never invent dates)
Root cause: one sentence
Fix: the exact change, quoted

... up to 5 patterns, ranked by cost to the user ...

## Proposed changes

## What went well

Step 5 — apply on confirmation

Number every proposed fix and let the user pick (all / numbers / none). Apply only what they picked. Rules must be short, imperative, and specific ("Run tests with pnpm vitest run, never npm test"), never vague ("be more careful with tests").

• Hooks/permissions: do not write settings.json schemas from memory — they

change between versions. Consult the harness settings docs or the update-config skill if available. Prefer project .claude/settings.json unless the rule is user-wide.

• If the user dictated "remember this" rules, auto-memory files

(~/.claude/projects//memory/) are a valid target alongside CLAUDE.md.

Hard rules

• Never invent evidence. Every quote must come from the scanner output or a

transcript you actually read; every date from a real ts.

• Fewer, sharper findings beat a long list. Zero real patterns is a valid

outcome — say so.

• Never modify CLAUDE.md, settings, skills, or memory without explicit

confirmation in this conversation.

• Everything stays local. Never send transcript content to any external

service.

• Do not treat scanner counts as truth; they are candidates. You are the

judge.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: craftwork-design
• Source: craftwork-design/retro
• License: MIT
• Homepage: https://craftwork.design

Install and usage instructions live in the source repository linked above.