Retro

Goal: the next session in that project does better without the user repeating themselves. Be selective: one real lesson beats five generic ones. Don't invent problems.

Input

digest=<path> transcript=<path> cwd=<project dir> session=<id>. Given only a transcript, run bin/crow-digest <transcript> to build the digest yourself. Batch mode: batch=<manifest> (written by crow-retro run). The manifest lists the window, the report path and one ### <project> <session8> block per kept session (session, account, cwd, digest, transcript, pre-filter signals). Run steps 1–3 for each session in turn with its own digest, transcript and cwd, then write the batch report (step 4).

Read the digest. Open the raw transcript only to check one specific moment (rg on it, never read it whole).

1. Find the signals

Read every 👤 User message, and the 🤖 message just before it. Look for:

• Correction: "no", "not X but Y", a fix to wording, language or format ("une MR", "shorter commit").
• Redirection: the user asked for something the agent didn't offer, or changed the plan.
• Stopped short: the user had to ask for a step the agent should have done ("push it", "I thought you had done this").
• Overreach: the agent did something the user then undid or refused.
• Repeated question: the agent asked something already answered in memory, a skill or CLAUDE.md.
• Friction: ⚠️ tool errors that repeat or cost several calls (missing binaries, wrong paths, expired auth, sandbox HOME), and workarounds found.
• Risk left behind: state that will bite later (work in /tmp or a scratchpad, uncommitted changes, unresolved threads, a missing reminder).
• Already learned: the session already saved a lesson itself (skill, memory). Check the file really holds it, then count it as captured, not as a new finding.

Also check upstream: did a prompt written by the hub (a pasted handoff or a dispatch prompt) cause the problem? If so, the lesson goes to the hub.

2. Check what already exists

Before writing, look at what the next session would load:

• Project: <cwd>/CLAUDE.md, <cwd>/.claude/skills/*/SKILL.md, <cwd>/.claude/skills/*/*.md
• Project memory: <claude config dir>/projects/<slug>/memory/ (the config dir is the parent of projects/ in the transcript path) with MEMORY.md (slug = cwd with every / replaced by -)
• Hub: runbooks/README.md, local/runbooks/README.md, .claude/skills/
• Earlier retros: rg -l "<keyword>" local/state/retros/*.md to count recurrences.

Before writing, check local/owner-prefs.md: a rule already there that the session broke means a repeat, so say so in the report and move it higher or sharpen it.

A lesson that exists but was ignored needs a sharper wording or a better place (skill step > memory > runbook), not a duplicate.

3. Decide and apply

For each finding, choose one:

Apply directly to: files git ignores in project repos, memories, and this hub's runbooks, skills and local/. Keep edits small and in the file's existing style. Never delete or rewrite content you didn't write, only add or sharpen. Generic vs private: runbooks/ is tracked and published, so it holds only generic steps. Any project, company, person, vendor, ticket or account name goes in local/runbooks/ (same file name, linked from local/runbooks/README.md). Check each runbook line you add against that before saving; do not rely on the pre-commit check to catch it. Propose everything else (tracked files in project repos, CLAUDE.md, code): append to local/state/retros/proposals.md as - [ ] YYYY-MM-DD <project> <file>: <change> (from <report>).

Commit your own hub edits at the end, one commit per repo: the hub repo for runbooks/ and .claude/skills/, the private local/ repo for local/. Stage only the files you edited (git add <path>..., never -A), keep the hub's commit format (chg[MD]: add retro lessons to ...), and list the commits in the report. If the pre-commit check rejects a private name, move that line to local/runbooks/ and commit again. Leave files someone else changed alone. Never commit in project repos, never push, post or message anyone. Never add AI attribution anywhere.

4. Report

Write local/state/retros/YYYY-MM-DD-<project>-<session8>.md, at most 30 lines:

# Retro: <project>, <date> (<session8>)
Task: <one line>
Outcome: <done / partly / abandoned, one line>

## Findings
| # | Signal | What happened | Lesson | Action |
|---|---|---|---|---|
| 1 | Stopped short | ... | ... | ✅ applied: <file> / 📝 proposed / ✔️ already captured / – ignored |

## Hub handoff
- <the prompt that started the session came from the hub (pasted handoff, dispatch, /retro)? did its wording cause any finding? "no hub prompt" / "ok" / "caused #n → <hub fix>">

## Risks left
- ... (only if any)

Batch mode: write the single report path named in the manifest (local/state/retros/YYYY-MM-DD-batch.md) instead, titled # Retro batch: <date>, with one ## <project> <session8> section per session holding the Task / Outcome / Findings / Hub handoff / Risks left lines above (at most 30 lines each). Don't write a skipped list: the script appends it. One activity line for the whole batch: - HH:MM [retro] batch: <n> sessions, <n> applied, <n> proposed.

Then append - HH:MM [retro] <project> <session8>: <n> applied, <n> proposed to today's activity log (local/state/activity/YYYY-MM-DD.md). Final message: the report path and one line per applied change.