← Skills

Retro

A retrospective on recent agent sessions in one repo. Finds where the agent struggled and proposes fixes to its environment, not to the agent.

Stage
Learn
Skill
retro ↗
Size
88 lines · 4 files
Updated
Nov 17, 2026

What it does

When an agent keeps making the same mistake, the fix is rarely a better prompt in the moment. It's a missing pointer in AGENTS.md, a lint rule, a hook, a script, or a skill rule. Retro looks at every session since the last retro in this repo and finds those gaps.

It presents findings and stops. I decide what to fix.

How it works

A script does all the deterministic work, so the agent never parses transcripts by hand:

python3 list_sessions.py --last-retro   # did last retro's fixes land?
python3 list_sessions.py --ledger       # lessons from other repos' retros that apply here
python3 list_sessions.py --scan         # failed calls, denials, slow calls, phrases I repeated

Then the agent sorts candidates by where the fix belongs:

  • Navigation: it took too long to find a file. Add a pointer.
  • Automated checks: a mistake a check could catch. Add the check, not a rule.
  • Coding standards: judgement calls only.
  • Repeated phrases: each thing I keep typing is a missing default.

Findings go into a shared ledger, so a lesson learned in one repo gets checked in the others.

What it made

A retrospective for a multi-agent Visual Notes run: findings in severity order

A retrospective on a multi-agent run in Visual Notes. Each finding names its consequence for the next run, and the fixes are commands and checks, not more reminders.

It's working if

  • The trend section shows last retro's numbers moving.
  • A finding that comes back a second time gets treated as more severe.

Read the skill

These are the files the agent loads, copied from byronwall/.agents. Copy one file, or download the folder as a ZIP and drop it into your own skills folder.

retro

4 files · ready to copy or download

SKILL.mdretro/SKILL.md
---
name: retro
description: "Conduct a retrospective on recent coding sessions in the current project and suggest improvements to the agent's environment. `/retro ledger` checks only what other repos' retros learned against this repo. Use when Byron says `/retro`, `$retro`, asks for a retro or retrospective, or asks whether the retro log has relevant items for this repo."
disable-model-invocation: true
---

The user has asked for a **retrospective**. You suggest improvements to the coding agent's **environment** to improve future runs. You present findings and stop; Byron decides what to fix.

## Modes

- `/retro`: the full retro below.
- `/retro ledger`: step 2 only. Check other repos' findings against this repo, present the ones that apply, and stop.

## Scope (defaults)

Unless the user says otherwise:

- **Project**: the repo you are running in, worktrees included. Go broader only when asked.
- **Harness**: the one you are running in (Claude Code transcripts or Codex rollouts). Read both only when asked.
- **Window**: every session since the previous retro in this project (3 days if none in the last 30). A user-named session, time frame, or count wins.

State the scope in one line at the top of your reply.

## Tools

Everything deterministic is in the script. Never `cat` a transcript and never write your own parser. If the script lacks something you need, add it to the script.

```bash
R=~/.agents/skills/retro/scripts/list_sessions.py
python3 $R --last-retro        # previous findings; PR landing checked against origin's default branch
python3 $R --ledger            # other repos' findings; runs their checks here
python3 $R                     # sessions in the window (--days N, --source claude|codex|all)
python3 $R --scan > $TMPDIR/retro-scan.txt   # window report; saves this retro's metrics
python3 $R --scan --section users            # one section, full text (sessions|trend|fails|denials|slow|users)
python3 $R --digest FILE       # one session plus its subagents
python3 $R --record FILE       # upsert findings into ~/.agents/retro-ledger.jsonl
```

Subagent transcripts fold into their parent session: `S3.a2` is subagent 2 of session 3.

## Steps

1. **Previous retro.** Run `--last-retro`. A PR that says "NOT on origin/main" did not land, whatever its status says. A finding that came back is more severe the second time; a ledger row with `seen 2x` or more is a repeat.
2. **Ledger.** Run `--ledger`. Each item that says **applies** goes into this retro's list, marked "from <repo>". For each **judge** item, decide from its lesson and a quick look at the repo. Skip items that are clearly irrelevant, without comment.
3. **Scan.** Run `--scan` and read it in this order:
   - **Trend**: the change since the last retro. A fix that didn't move its number is a finding.
   - **Phrases you repeated** and **Likely corrections**: each repeat is a missing default, check, or skill rule.
   - **Failed calls**, **Permission denials**, **Slowest calls**: these point to the sessions worth a `--digest`.

   Open raw transcript lines only to confirm one finding. With more than ~10 sessions to dig into, hand batches to subagents that return findings with evidence.
4. **Look for candidates** in these categories:
   - **Navigation**: the agent took long to find a file or fact. Fix with a **navigation pointer**.
   - **Automated checks**: an agent mistake that a check could catch, or a repo with no **guardrail** (pre-commit hook running lint/typecheck/test). Read the repo's own check scripts and CI first; a check that exists but is unwired or broken is the finding. Suggest CI only where CI exists.
   - **Coding standards**: the reviewer missed a mistake. A **mechanical** violation gets a deterministic check (lint rule, hook, or existing CI job), not a rule. `CODING_STANDARDS.md` holds judgement calls only.
   - **Verification**: the agent declared success without evidence (unviewed screenshots, skipped checks, no real run), or the user found a defect the agent should have seen.
   - **User steering**: a phrase repeated across sessions, or a correction. Each one is a missing instruction, check, or skill default.
   - **Permission denials**: a repeated denial reason means a brief, a script file, or an allowlist entry is missing.
   - **Steering files**: a large `AGENTS.md`/`CLAUDE.md` (repo or global). Move rules to checks or standards, and delete lines that change no behavior.
   - **Tool economy**: expensive or token-heavy calls, including custom CLIs and MCPs.
   - **Information access**: a crucial fact the agent could not reach (dev server logs, deploy SHA, read-only service access).

   [references/where-fixes-live.md](references/where-fixes-live.md) says where each kind of fix belongs.
5. **Present** a numbered list in order of severity, so the user can answer "do 1, 3, 5". For each item give:
   - the evidence (session and a short quote, tool error, or metric),
   - the fix and where it lives (check, `CODING_STANDARDS.md`, `AGENTS.md`, repo skill, global skill, or a setting Byron must change),
   - its history: new, a repeat (with count), or from the ledger (with source repo).

   Then a short **What went well** list: patterns to keep, so a fix doesn't break them.
6. **Record** every presented item with `--record`, status `proposed`. Use one JSON object per item:

   ```json
   {"key": "no-precommit-guardrail", "scope": "repo", "title": "No pre-commit hook runs lint and typecheck",
    "fix": "Add .githooks/pre-commit running pnpm lint + type-check", "target": ".githooks/pre-commit",
    "lesson": "Every repo needs a local hook running its lint and typecheck",
    "check": "! git config core.hooksPath >/dev/null && [ ! -x .git/hooks/pre-commit ] && [ ! -d .husky ]",
    "status": "proposed"}
   ```

   - `key`: a stable slug. Reuse the ledger's key when the same problem shows up again, so repeats accumulate on one row.
   - `scope`: `repo` or `global`. Only `repo` items are offered to other repos.
   - `lesson`: one line that another repo can act on without this repo's context.
   - `check`: for mechanical items, a zsh command run at a repo root that exits 0 when the problem is present. Leave it out for judgement items.
7. **Stop.** Don't start fixing until Byron picks items. When he picks:
   - For each item, compare a few options with `consider-contrast` and pick the best or a hybrid.
   - Repo changes go out as stacked PRs, one item or a tight group per PR.
   - Edit global skills in place under `~/.agents/skills/`, with no PR.
   - Record the result: `picked` or `done` with `prs`, and `declined` for items he passed on.
markdown87 lines