retro

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

   ```bash
   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:

   ```bash
   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:

   ```bash
   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:

   ```bash
   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.

From Necmttn/ax, AGPL-3.0.

More from Necmttn/ax