Run once per session, at the end, before the final status. The point is not ceremony — it is noticing what the session revealed that its deliverable didn't capture: tool gaps, repeated mechanics, ignored debt.
Checklist
- Loose ends.
git statusclean? PRs merged, watched, or handed off?bdin_progress = 0 or justified? A dirty tree at session end is lost work — same for an unwatched PR. - Hand-rolled mechanics → codemod candidates. Every ad-hoc script,
jq pipeline, or multi-step shell one-liner written this session is a
signal: if the mechanics are general,
broshould own them. File abdgap bead (title says the missing command, body quotes the one-liner that had to be invented) — or implement it if the surface already exists. Example that made this real: a hand-writtenagents.jsonprune script →bro-k7a1(bro fleet agents prunemissing). - Call economy. Count the calls that repeated one pattern —
N
bd closes, Ngh apifetches, N status polls. If onebrocommand could batch them, that is the same kind of gap bead. - Lessons. Persist what this session learned — a dry-run alone
stores nothing.
bro self learn capture --dry-runpreviews what finished artifacts would distill — capture has no session filter, so a plan that is all this session's gets stored by rerunning barecapture; otherwise store just this session's insight withbro self learn add --lesson "…" --on … --evidence …, so the next session starts smarter, not just the next human. - Debt sweep. PRs merged this session →
bro review debt collectpicks up reviewer findings left unresolved. Never leave them to rot. - State assertions. Verify from authoritative checks, not memory:
gh pr viewfor merges,git worktree listfor cleanup,bd showfor beads. A watcher exit is a state to inspect, not silence.
Policy
- Scale to the session. A one-shot Q&A that touched nothing skips with a single line — retro is a review, not busywork. A session that wrote code, merged PRs, or spawned agents does the full pass.
- Beads, not prose. Findings land as
bditems — never as a paragraph the user has to convert into work themselves. - The guard is the doorbell, this skill is the room. The
retro-on-stopguard fires the one-line nudge; this checklist is what "ran the retro" actually means.