workflow-retro

/workflow-retro — multi-agent run retrospective

Run this right after a multi-agent workflow (typically /run-plan, or any session where several subagents were spawned) to turn what just happened into a durable, comparable record. The point is not a pretty report — it's to make the next run spend fewer tokens and repeat fewer mistakes. Zero new LLM calls: everything comes from what is already in this session's context plus cheap git/filesystem reads.

Its ONLY output is a file under .claude/workflow-runs/ — it never edits agent definitions, plans, specs, or code. It proposes tuning; a human applies it.

Where the data comes from (reconstruct, don't invent)

You already have the evidence in-session — harvest it, and be honest about estimates:

• Agent timeline & order — the Agent (Task) spawn calls you made this session, in order, and whether they ran in parallel (multiple in one turn) or sequentially. Note each agent's role (implementer, architecture-reviewer, plan-verifier, researcher, …) and whether it was [SPAWN] or done [INLINE].
• Per-agent cost — each finished subagent's <usage> notification carries subagent_tokens, tool_uses, and duration_ms. Use those literal numbers.
• Session total — the exact figure comes from /context (the user runs it); record it as an estimate and say so. Never fabricate a token/cost number — if you don't have it, write —.
• What landed — git diff --stat / git log --oneline (read-only) for the files/commits the run produced.
• Qualitative signals — from the transcript: where an agent struggled or looped, what it asked, what a later step revealed a earlier one missed, and any file read by several agents.

Procedure

1. Identify the run

The workflow (/run-plan <slug> etc.), the plan/spec it consumed, the branch (git rev-parse --abbrev-ref HEAD), and today's date (date +%F).

2. Rebuild the agent timeline

Ordered list of every agent launched: role · mode (parallel/sequential, SPAWN/INLINE) · subagent_tokens · tool_uses · duration_ms · outcome (clean / needed rework / failed).

3. Totals

Agents launched, summed subagent tokens, session tokens (est. from /context), review→fix rounds, wall-clock if known.

4. Qualitative insights (the useful part)

• Hard vs easy per agent — where it thrashed vs one-shotted.
• Duplication — the same file/context re-read by N agents; work redone.
• Gaps — what a later stage caught that an earlier one should have (missed edge case, wrong assumption, an AC with no coverage).

5. Extra eval signals

• Spawn-economy audit — did a cold-start agent get spawned for trivial work that should have been [INLINE]? Wasted fan-out (parallel agents that didn't need to be separate)? A slice that should have been merged? (Rules: this plugin's own README, "Spawn economy" section.)
• Rework / iteration cost — review→fix loops, retries, and tokens spent on work that was later discarded or redone. Call out the single most expensive avoidable loop.
• Trend vs previous runs — ls .claude/workflow-runs/ and read the most recent prior retro (same workflow if possible); report deltas: tokens Δ, agents Δ, review-rounds Δ, and whether a previously-noted recommendation was actually applied.

6. Recommendations (propose, never apply)

Concrete, actionable tuning for next time — e.g. "inline the barrel-export slice, don't spawn", "spec-creator missed the token budget → its final self-check already covers it, so the miss was execution not spec", "route docs/ reads through one researcher instead of three". Each recommendation names the target (an agent, the plan shape, or the orchestration) and the expected saving. You do not edit those files — you list the changes for a human to make.

Output file

Write .claude/workflow-runs/<YYYY-MM-DD>-<workflow>-<slug>.md (date from date +%F). If a file for the same run already exists, add a -2 suffix rather than overwriting. Use this shape:

# Workflow Retro: <workflow> — <slug>  |  <YYYY-MM-DD>
Workflow: /run-plan <slug>   ·   Branch: <branch>   ·   Consumed: <spec / plan refs>

## Run summary
- Agents launched: <N>
- Subagent tokens (summed): ~<X>   ·   Session tokens (est., /context): ~<Y>   ·   Cost: <— or $>
- Review→fix rounds: <R>   ·   Duration: <— or s>

## Agent timeline
| # | Agent | Mode | Tokens | Tool calls | Duration | Outcome |
|---|-------|------|--------|-----------|----------|---------|
| 1 | … | SPAWN·parallel | … | … | … | clean |

## What went well / hard
- <agent>: <easy / hard, with why>

## Duplication & gaps
- Duplicated: <file/context re-read by N agents>
- Missed: <what a later stage caught that an earlier one should have>

## Spawn-economy audit
- <cold-start-for-trivial? wasted fan-out? INLINE-should-haves?>

## Rework / iteration cost
- <review→fix loops, retries, tokens on discarded work; the costliest avoidable one>

## Trend vs previous runs
- vs <prior retro filename>: tokens <Δ>, agents <Δ>, rounds <Δ>; prior rec applied? <yes/no>

## Recommendations (proposed, not applied)
- <target> → <change> → <expected saving>

Honesty & anti-banality

• Estimate honestly. Per-agent tokens are the reported subagent_tokens; the session total is a /context estimate — label it. Blank (—) beats a made-up number.
• Only non-obvious, actionable lessons. "The run used tokens" is noise. "Three agents each re-read the same package's lessons-learned file; pass it once in the spawn prompt" is signal.
• Append-only across runs. Each run is its own file; never rewrite a past retro. Correct a stale conclusion in the new run's Trend section, referencing the old file.

Report back

Reply in the language of the request: the retro file path, the headline numbers (agents, tokens, rounds), the top 2–3 recommendations, and the trend vs the last run. Point to the file; don't paste it whole.