agent skill for retrospective in a team of 3 agents

retrospective-skill.md

name	retrospective
user-invocable	true
description	Run a team retrospective on recent cycles and produce one concise, focused improvement report: where each lesson belongs (knowledge base / skills / agent instructions), which tools to improve or add (shell / bake / arch-fitness), tool output & performance fixes, and the top time/token effort drivers. Keywords: retrospective, retro, lessons learned, improvement report, effort drivers, tool effectiveness.

Retrospective

Gather the whole team's experience since the last retro and produce one concise, focused, prioritized improvement report. Analysis only — make no changes; each accepted item becomes its own normally-planned task.

Conciseness is a hard requirement. Tables and one-line items, not prose. No paragraph walls, no restated background. Every item is on-point: target → concrete change (why) in one line. Cut anything that does not change a decision. A noisy report is a failed report.

The four questions the report must answer

1. Knowledge placement — for each lesson worth keeping, WHERE should it live?
   • knowledge base (docs/Manual) — stable concepts, domain, architecture;
   • a skill — repeatable workflow / tool usage;
   • agent instructions (.github/copilot-instructions.md or a role prompt) — agent behavior. Give: target + the concrete add/move/clarify + why.
2. Tools — quality & productivity — which existing tool to improve, or which NEW tool to add (shell script, bake extension, or arch-fitness AFxxx function), with the concrete win.
3. Tool output & performance — which tool's output is too noisy, or which tool is too slow, and the fix.
4. Effort drivers — what consumed the most time and the most tokens this window (these can differ), plus the single highest-ROI fix.

Cycle scope — since the last retro

Cover only cycles since the previous retro (never re-cover retro'd work) unless the user gives a window. The previous boundary is in memory (subject retro cadence: date + issue list + commit range). If none exists, fall back to the session start or ask. After delivering, store a new retro cadence memory (date + cycles + <first>..<last> commit range).

Steps

1. Frame the cycles — list each cycle since the boundary with its landing commit.
2. Compute statistics — Tables A and B below.
3. Gather team input — notify Implementer and Verifier (./swarmtools/notify-agent.sh <role> --file ./tmp/<file>.txt); each replies to agent_context/retro-<role>.md (shared folder, not per-worktree tmp/). Ask the four questions above and one Table-B row per tool they used. Keep the request short; do not prescribe answers.
4. Mine agent_context/lessons-log-<role>.md, the role replies, and your own session experience for recurring friction and near-misses.
5. Synthesize one report. Mark [CONVERGED] where both roles raised an item independently (strongest signal). De-duplicate ruthlessly.
6. Deliver to the user and ask which items become tasks. Implement nothing.
7. Record the retro cadence memory.

Statistics — two tables, no prose between them

Source: session store if available (exact); else fallback estimates from agent_context/logbook.json timestamps + observed command runtimes — label as estimates and note the store was down. Do not block the retro on a missing store.

Table A — Effort drivers (top 3-5, ranked):

Driver (cycle / command / activity)	Time	Tokens	Note

• Time: summed wall-clock; resolve bash to the real command (bake verify, bake compile, git, dotnet test, sub-agent task), never bucket as "bash".
• Tokens: from session store usage_*_tokens when available; else flag the token-heavy actions (full-file reads, large tool outputs, sub-agent runs, long reports) — time-cheap but token-expensive items belong here too.

Table B — Existing-tool effectiveness (one row per tool actually used):

Tool	Used	Hit / Miss	Verdict (keep / improve / drop)

Cover the discovery tools (discover.sh def/symbols/specs/term/related, the symbol index, find-entry-points/explain-area/find-callers) and any bake/test tool exercised this window. Terse cells.

Report shape (the whole report)

1. Statistics — Tables A + B.
2. Improvements — grouped under the four questions; each item ONE line, target → concrete change (why); tag [CONVERGED] where both roles agree.
3. Shortlist — quick wins vs larger investments, one line each.

Nothing else.

Stop conditions

• Analysis only — no code/doc/tool/rule changes during the retro.
• A role that doesn't reply: proceed with the rest, note the gap.
• Session store unavailable: label stats as estimates; continue.