Retro

A run that went badly once will go badly again unless something in the setup changes: the team config, a repo's checks or instructions, or roost itself. The retro reads what actually happened in a session, finds the moments that cost time or trust, and proposes the change that stops each one recurring, in the place that can enforce it.

First, load the team config with roost-config.

For now the retro covers one session: this one, or one the user names. It reads only that session's own transcript, never a subagent's.

Rules

• Read-only until the user decides. Before the checkpoint, never edit a file, the team config, a repo or roost, never file or change a ticket, and never message a session.
• The retro never runs a check itself. A hypothesis's check is run by the user or a repo session, or ticketed.
• Every finding has evidence. A finding whose problem isn't in the script's output, the transcript or the tracker isn't reported, however likely it seems.
• Quotes come only from the script's output, which is already redacted. Never paste text from the transcript into a finding, a ticket or a handoff; cite the moment's session and time instead.
• The retro never edits the team config or a permission settings file. An accepted config change or permission rule is shown for the user to make.

1. Find the transcript

If the user already gave you the script's output for the session, skip to step 3: don't look for the transcript or run the script again.

Transcripts are ~/.claude/projects/<folder>/<session id>.jsonl, one folder per working directory. Don't build the folder's name from the path (characters such as ., _ and spaces are changed in it); find transcripts by what their records say: each record has the session's working directory as "cwd".

• "This session": the transcripts whose records have this working directory as their cwd (grep -lF '"cwd":"<this directory>"' ~/.claude/projects/*/*.jsonl, a fixed string, so . and [ in the path match only themselves); of those, the newest that contains the user's last message. Say which file.
• A named session: search every folder under ~/.claude/projects/, not only this directory's: a repo session's transcript is in its own repo's folder. Match the name against each transcript's custom-title and agent-name records, written with no space after the colon (grep -lF '"customTitle":"<name>"' ~/.claude/projects/*/*.jsonl, and the same for "agentName":"<name>"). If none matches, or more than one does, list what you found and ask which.

2. Run the script

python3 <this skill's folder>/scripts/retro_moments.py moments <transcript> --config <team config> [--config <override>]

The script is skills/retro/scripts/retro_moments.py; run it from this skill's own folder. Pass the team config and then each override file roost-config applied, in that order: the script redacts their identifying values (the tracker site and IDs, hostnames, URLs, IP addresses, the test account pattern) and generic secrets from every quote, and drops a quote it can't clean.

It prints one JSON object: moments (each with its kind, session, time, record id and excerpt; slow steps grouped by command with each run), sessions with totals per session, unreadable transcripts (files it couldn't open, or that failed while being read), unparseable records, unknown_types, unknown_shapes (records that look like a hook's block or a delivery notice, in a shape the script doesn't read yet), subagents_not_read and redaction.

3. Read the moments

Read every moment and the totals. Open the transcript around a moment only when the excerpt isn't enough to say what happened, and quote only the script's excerpt.

A correction moment is only a candidate: the script marks each message the user typed after their first, except the interruption a rejected permission prompt writes. A go-ahead or an approval ("yes", "proceed", "merged", "looks good") isn't a correction, and nor is the user's answer to a question the agent asked. Only a message that changes or rejects what the agent did ("we don't use moment here", "that's the wrong repo") can back a finding. The user interrupting the agent ([Request interrupted by user) is a real correction too: they stopped what it was doing.

A refusal moment is a tool call that didn't run; its how says who stopped it:

• user-rejected: the user said no at a permission prompt. That's the user's judgment, like a correction: the agent tried something they didn't want. The prompt's own "[Request interrupted by user for tool use]" isn't counted again.
• automode-blocked or automode-unavailable: auto mode stopped the call, not the user. Nobody said no to that call: it points at what the session was allowed to do, not at the user's view of the work, so its finding is in the Permissions and auto mode area of references/finding-areas.md (or roost itself, when a roost skill asked for the blocked action). An interruption after it is a real correction.

4. Write the findings

Use references/finding-areas.md: each finding names its area, which decides where the fix goes, and has what happened, its evidence (the moment's excerpt, session and time), what skipping it costs with a concrete case, a recommendation marked Checked or Hypothesis, and where the change goes. Rank them there too.

• A mechanical mistake is a check (a lint rule, a hook or a CI job in the repo); a review miss is a review rule (added to the repo's existing review_focus; when the repo has none, start from planning.review_focus, since a repo's own replaces it; or the repo's coding standards). Neither is only a line in CLAUDE.md or AGENTS.md.
• A slow step is one finding with its count and total, never one per run. A skip or a speed-up you can't prove from what you've read is a Hypothesis that names its check, who can run it and how long it takes.

5. The checkpoint

Show one ranked list, most severe first:

• Severity: High, Medium or Low.
• Recommendation: starts Checked: with its evidence, or Hypothesis: with the check, who can run it and how long it takes against what the problem costs.
• Where: Team config (and the key), a repo's name, Permissions (the settings file and the tool), or roost.

End with: "Decide each by number: a Checked finding takes yes or no; a Hypothesis takes check now, ticket the check, or skip." Then stop and wait.

A "yes" on a Hypothesis isn't one of its choices: ask again which of the three it is. Never treat it as approving the change: the change waits for the check.

6. Give each accepted finding a home

Only after the user decides, and only for what they accepted:

• A team config change: show the key and its new text for the user to make. Don't edit the config.
• A permission rule: name the settings file and the tool, with the moment's session and time, for the user to write the allow rule. Don't copy the command from the transcript, and don't edit any settings file.
• A change in a repo: a ticket for that repo with a cross-repo-handoff prompt that its session can act on.
• A change to roost: list it in the report for the user, with its evidence. Don't draft or file a roost issue: roost's tracker is public, and the retro doesn't yet swap the team's names for example names or check a draft for private details.
• A hypothesis, "check now": give the user the check's steps (or what to tell the repo session), wait for the result, then mark the finding Checked or drop it.
• A hypothesis, "ticket the check": ticket the check, not the change. A check a repo session can run is a ticket for that repo, with a cross-repo-handoff prompt. A check only the user can run is a person-owned task (labelled tracker.person_task_label, default person-owned) for the user, with its steps and the result that confirms or refutes the hypothesis. The change waits for that result.
• Skipped or rejected: nothing is filed.

Before filing any ticket or person-owned task, check its text, so no path, username or configured value leaves this machine:

1. Write its title to one file and its body (with any cross-repo-handoff prompt) to another, exactly as they'll be filed, and show both to the user.

2. Run the check with the same configs and the run's transcripts, so it knows the session's username:

   python3 <this skill's folder>/scripts/retro_moments.py check <title file> --config <team config> [--config <override>] --transcript <transcript>...
   python3 <this skill's folder>/scripts/retro_moments.py check <body file> --config <team config> [--config <override>] --transcript <transcript>...

   When the user gave you the script's output instead of a transcript (step 1), there's no transcript to pass: ask them for the session's working directory and pass it as --cwd <directory>. Pass --no-users only when the user says the session ran outside any home folder.

3. File it only when both checks pass (exit 0, "passed": true), and file from those same files: the body with the tracker adapter's create-from-a-file (--body-file <body file> for GitHub) and the title read from its file (--title "$(cat <title file>)"), never text typed again. Any edit after the check, however small, means checking that file again before filing. On a hit (exit 3), show the user each one (kind: path, config, user, secret or unsure, a string redact would withhold; line, column, length; and key for a configured value or reason for unsure), fix the text, and check again. When the check can't run (exit 4, with a reason: a transcript it can't open, or no usernames to look for), file nothing: give it the transcripts or --cwd it asks for, and check again. Never file a draft that failed, and never work around a hit by rewording the check's input.

Report

One line: "Retro on acme-api-3f: 4 findings, 2 accepted, 1 check ticketed, 1 skipped." Then each home made, with its link. Then, when there are any, each of these, never skipped silently:

• A transcript that couldn't be opened or read (unreadable): which session, and why ("can't read the file", or "couldn't be read" when it failed partway); the retro covers the rest. These are whole files, not the unreadable records below.
• Unreadable records (unparseable, unknown_types): "3 records couldn't be read (2 not JSON, 1 incomplete last line); 1 unknown record type."
• Unknown shapes (unknown_shapes): "2 records look like a hook's block; retro doesn't read that shape yet, so they aren't in the findings: <session>, lines 77 and 140."
• Subagent transcripts (subagents_not_read): "2 subagent transcripts weren't read; retro reads only the sessions' own transcripts."
• Withheld quotes (redaction.dropped): "2 quotes withheld; their findings cite the session and time."