Retro

ax:retro - guided experiment-loop session

Closes the self-improvement loop. Claude orchestrates ax improve … commands; the user decides each row.

Assumes ax (axctl) is on PATH. If ax improve list fails, tell the user to check docs/development.md#setup (DuckDB dylib setup - no daemon required) and stop.

When to fire

ONLY fire on explicit triggers:

• "let's do an ax retro" / "ax retrospective" / "retro time"
• "review my ax proposals" / "triage proposals"
• "what's my experiment loop status" / "lock pending verdicts"
• "hook effectiveness review" / "intervention review"
• "self-improvement session"
• /ax:retro slash command (if the plugin marketplace publishes one)

Do NOT fire on a generic "look at my recent work" - that risks dragging unrelated context into the loop.

Defaults

• Window for hook signals: last 7 days. Widen to 30 if evidence is sparse.
• Don't apply changes silently. Every accept/reject/verdict gets the user's explicit yes per row.
• The retro is read-mostly. Its side-effects are the Step 1 checkpoint measurements, the task briefs accept emits, and verdict locks.

Workflow

Step 0 - Drain pending session retros

Before the proposal queue, check whether prior sessions still owe a retro. This is the "quota arbitrage" path - idle Opus budget chews through the backlog so the experiment loop has signal next time.

1. Run:

   ax retro pending --since=7 --idle-min=30 --json

   Returns sessions in the last 7 days that have no reviewed graph edge yet AND look finished (explicit ended_at, or last turn is

   30min idle). If the list is empty, skip to Step 1.

2. Show the list to the user as 1 line per session (project · turns · model · reason). Ask:

   N session(s) pending retro. Want me to dispatch the retro-reviewer subagent for all of them in parallel, or pick a subset?

3. On all or <subset>: for each chosen session, write a brief:

   ax retro brief --session=<session_id>

   This writes .ax/tasks/retro/<key>.md with frontmatter (transcript path, suggested model, turn count, etc.) and a body that tells the reviewer what to do.

4. Dispatch one retro-reviewer subagent per brief, in parallel. Pass each brief path in the prompt; let the subagent's frontmatter pin model: opus (override per session if suggested_model differs and the user asked you to economize).

   If the retro-reviewer subagent type doesn't resolve (not installed, or the active harness is not Claude Code), read and review the brief INLINE using its required-output instructions instead of abandoning the backlog.

5. Wait for all subagents. Aggregate results: counts of retros emitted, proposals recommended, model-fit suggestions. Render as a short summary. The user does not approve retro emissions per row - the subagent already wrote them. The user DOES decide on resulting proposals in Step 2.

6. The reviewed edge now exists for each drained session, so a re-run of ax retro pending should show fewer rows.

If the user declines Step 0, move on. The backlog stays - next retro picks it up.

Step 1 - Snapshot

Measure first, then read. The checkpoint pass is what turns due windows into current ones; a verdict read taken before it reports whatever the last run happened to leave behind.

1. Run the prerequisite ALONE and wait for it:

   AX_NO_AUTO_INGEST=1 ax improve checkpoint --json

   It reads the published snapshot and writes checkpoint judgments only - no transcript parsing, no guidance edits, no verdict locks. Leave --force out of an ordinary retro; it rewrites unreviewed windows that are already current.

2. On success, run the reads (parallel is fine). Prefix EVERY command - a prefix on the first one leaves the freshness drive on for the rest:

   AX_NO_AUTO_INGEST=1 ax improve list --status=open --json
   AX_NO_AUTO_INGEST=1 ax improve list --status=accepted --json
   AX_NO_AUTO_INGEST=1 ax improve verdict --json
   AX_NO_AUTO_INGEST=1 ax retro list --since=7 --json        # cluster-derived friction summary
   AX_NO_AUTO_INGEST=1 ax hooks summary --since=7 --tail=20  # optional; tolerate failure

3. If the checkpoint run fails, tell the user measurement is unavailable and continue with proposal review only. Any suggestion already stored belongs to an earlier run - report it as that, and skip the verdict step.

4. If the checkpoint result reports cacheRefreshRequired above zero, the opportunity evidence needs deriving; say so, and treat those experiments as unmeasured. When the user asks for current evidence, run three operations in order, each awaited on its own: ax ingest (wait for successful publication), the checkpoint prerequisite, then the reads.

ax retro list reflects three pattern types now:

• tool failures (skill form) -> Pre-<Tool> guard proposals
• correction pressure (guidance form) -> "Reduce recurring user corrections" proposals targeting CLAUDE.md
• friction kinds (skill form, one per kind) -> Address recurring <kind> friction proposals

If any of those surfaced, mention them so the user knows to triage in Step 2.

Compute counts: open proposals (by form), accepted experiments with locked_verdict IS NONE, and - separately - experiments whose current view carries a current_reason (insufficient data or a lifecycle state). Then render to the user as 2-4 lines, e.g.:

7 open proposals (3 skill, 4 guidance). 2 accepted experiments are waiting on a verdict. Hook activity last 7d: 142 invocations, 3 blocking errors. Want to triage proposals first, lock the pending verdicts, or skim hook signals?

If both proposal/verdict queues are empty: tell the user nothing's due and offer ax ingest --derive-only to refresh evidence.

Step 2 - Triage open proposals

Order open proposals by frequency desc. For each, in turn:

1. Run ax improve show <dedupe_sig> --json (or reuse the row from step 1).

2. Render as 3-5 lines. Example for a skill proposal:

   Schema change guardrail (skill · freq=9 · confidence=high) Hypothesis: schema edits often surface in fix-chains within ~14d. Trigger: fix commits overlap schema files. Behavior: run schema lint + one read/write smoke before edit.

3. Ask the user: accept, reject, or skip.

4. Branch:

   • accept → run ax improve accept <dedupe_sig>. By default this emits a TASK BRIEF and returns its task_path; it does not install the artifact. Report that path. Offer: "Want me to implement the brief now?" If yes: implement it, then run ax improve lint so ax reconciles the marker it finds on disk and records the installed artifact. Until lint records one, the experiment has no measurable installation.
   • reject → ask for a short reason (≤80 chars). Run ax improve reject <dedupe_sig> --reason "<reason>".
   • skip → no command. Move on; the proposal stays open for the next retro.

After the loop, summarize: "Accepted 3, rejected 1, skipped 2."