Retro

Find every moment a human had to step into the loop, and propose the mechanism that makes each one unnecessary next time. The fix for a bad session is a missing part of the harness, not a better prompt — so every finding must end at something that can be built, wired, and run without the user remembering to ask.

An observation with no proposal is a failed retro. So is a proposal the user cannot act on without a follow-up question.

Produce the report in one pass. Do not interview the user first and do not ask permission to begin.

1. Scope the session

Default to the current session. Locate its transcript the way this harness exposes one — a transcript store, a resume listing, a log directory — rather than assuming a path. Find an earlier session the same way.

Use both sources: the transcript carries the narrative arc (user messages, re-prompts, what was said out loud), the live context carries tool calls, results, and reasoning. If the session was compacted, say so in the report and treat tool-level detail from before the boundary as unreliable — compaction is itself a finding (§2).

2. Find the interventions

Scan for every point where a human had to act for the system to keep making progress:

Record each with its turn and one sentence of what happened. The count matters less than whether each one is likely to recur.

Note briefly which existing mechanisms caught something before the user had to. Those are the parts of the harness paying off and worth extending.

3. Diagnose each intervention

Answer one question: what did the system not know, not check, or not reach?

• Not know — information existed somewhere but never reached the agent. Missing feedforward.
• Not check — the agent produced something wrong and nothing tested it. Missing feedback.
• Not reach — the information or tool existed but the agent had no way to touch it, so the user became the wire. Missing capability.

Name the root cause, not the symptom. "The agent wrote a bad migration filename" is a symptom; "the filename algorithm lives in a generator the agent never ran" is the cause, and it points at a different mechanism.

4. Choose a mechanism

Run each root cause down this funnel. Stop at the first level that can carry the judgment.

1. Encode it deterministically, if the judgment can be. Inference is inconsistent; compile yesterday's judgment into tomorrow's tooling.
2. Constrain what gets made, or verify what was made? Constraining is cheaper — a generator, template, or schema means the agent never has to know the rule. Verifying is a linter, test, or check.
3. Can the agent invoke it, and does its output flow back without a human? If not, the mechanism is unfinished: add the hook, the allowed command, the connector. A tool the user has to run and paste is still plumbing.
4. Can a narrow agent judge it after the fact? A review skill with a single thesis of quality, run as a subagent so it does not spend the main context.
5. Instruction text, only if none of the above reach — and only as a routing line ("when touching X, run Y"), never a transfer of judgment.

Tag every proposal with its quadrant (model from Birgitta Böckeler):

Inferential feedforward is the trap: the one quadrant that is never enforced, only hoped for. If most proposals land there, the analysis stopped too early — go back to §4.1.

Three rules constrain every choice:

• Repair a blind sensor before adding a layer on top of it. If a check fired and the agent misread it, the fix is that check's output — a clearer failure message, a wrapper reporting the actionable part — not an instruction explaining how to interpret it.
• Remove the human from the wire before optimizing what flows through it. A plumbing intervention is a capability or wiring problem first.
• Propose portable mechanisms — a skill, a hook, a script, a doc — not a rule file that only one harness reads.

Mechanism catalog

5. Filter

Cut proposals that fail any of these:

• Recurrence. Would this friction plausibly happen again? A one-off misunderstanding needs no mechanism; recurring steers need one most.
• Cost. Every mechanism costs wall-clock time on every run, or agent attention on every turn, forever. Say the cost out loud for each proposal.
• Goodhart. Would the agent optimize this against the underlying goal? Proxy metrics — quality scores, coverage thresholds, complexity budgets — are where this bites. Prefer checking a property over scoring one.
• Buildability. Could the user say yes and get a working thing? If it needs a design conversation first, it is not ready.

Three proposals the user will build beat nine they will skim.

6. Report

Keep it dense. No preamble, no recap of the session's content. Name what went wrong plainly — "opportunity" is not a finding.

## Session

One or two lines: what the work was, where the time actually went,
whether the transcript was complete.

## Interventions

| # | Turn | What happened | Type | Root cause |

## Proposals

For each, in priority order:

### N. <Imperative title>
**Quadrant** · **Cost:** <what it costs on every run>
What it is, in one or two sentences.
**Build:** the concrete artifact — file path, what it checks, what it
refuses, what the failure message says.
**Wiring:** how its output reaches the loop without a human.
**Evidence:** the intervention(s) it removes.

## Considered and rejected

One line each, with the reason.

## Open questions

Only where a recommendation genuinely turns on something the transcript
cannot show. Omit the section otherwise.

Rank proposals by leverage: how much intervention each removes, divided by cost to build and cost to run. Deterministic mechanisms that constrain generation usually win.

7. Build

Close with one line: which to build. On assent, build immediately and fully — write the hook config, the generator, the script, the skill file — and verify it runs. A retro that ends in a list of good intentions has failed the same way one that ends in observations has.