Retro Meta

ax:retro-meta - deep retro of retros

The companion to ax:retro. Where ax:retro walks the heuristic-derived proposals one by one, retro-meta asks: what improvements does the existing pipeline NOT yet see?

The external agent (this one, Claude Code or Codex with high thinking) drives the reasoning. The CLI just produces structured evidence and takes user-approved plans back.

When to fire

Explicit triggers only:

• "let's do a deep retro" / "retro of retros"
• "investigate my ax setup" / "what should I fix in my setup"
• "review proposals the heuristic missed"
• /ax:retro-meta slash command
• After ax:retro finishes if the user wants broader exploration

Do NOT auto-trigger on generic "look at recent work".

Prerequisites

• ax (axctl) is on PATH. If ax doctor fails, stop and point the user at docs/development.md#setup (DuckDB dylib setup - no daemon required).
• At least 3 retros in the last 30 days. Below that, evidence is too thin for a meta pass - recommend ax:retro first.

Workflow

Step 1 - Snapshot

ax retro meta --json --since=30 > /tmp/ax-meta.json

Read /tmp/ax-meta.json. The keys you care about:

• experiment_status[] - read this FIRST (see Step 2). Each entry: experiment_id, proposal_dedupe_sig, proposal_title, proposal_form, artifact_path, days_since_accepted, opportunities_count, addressed_count, address_ratio, latest_checkpoint{kind,suggested,observed_at}, locked_verdict. Pending verdicts (locked_verdict=null) come first.
• retros[] - raw tried/worked/failed/next per session.
• patterns.tool_failures - sorted by total_count desc.
• patterns.corrections - total + max-per-session + session_count.
• patterns.friction_kinds - recurring kinds across sessions.
• current_state.skills - what's already installed (do NOT propose duplicates).
• current_state.open_proposals - existing heuristic proposals.
• current_state.accepted_experiments - accepted but verdict-pending.
• current_state.claude_md_user / claude_md_project - guidance file paths (null if absent).
• investigation_prompts[] - the prompts you must walk.

Step 2 - Vet existing experiments FIRST

Walk experiment_status in order. For each entry with locked_verdict=null:

a. If latest_checkpoint.suggested is ignored or regressed: investigate why (read the artifact_path, sample the matching opportunities), then run ax improve verdict --set=<v> <proposal_dedupe_sig> to lock the call. b. If latest_checkpoint.suggested is adopted AND days_since_accepted > 30: lock it as adopted so it stops cluttering the open list: ax improve verdict --set=adopted <proposal_dedupe_sig>. c. If latest_checkpoint is null OR suggested is partial: leave open. Note in the final summary that it's still gathering signal.

A rule of thumb mirrored from investigation_prompts: if address_ratio < 0.1 after t+30, default to locking as ignored unless the artifact has an obvious "not yet exercised" reason.

Step 3 - Walk the investigation prompts (high thinking)

For EACH prompt in investigation_prompts:

1. Inspect referenced state with Read / Glob / Grep:
   • skill files in ~/.claude/skills/ and ~/.agents/skills/
   • claude_md_user if non-null
   • claude_md_project if non-null
2. Reason about a candidate improvement. Use a high thinking budget - the point is to see what the heuristic missed.
3. If you identify a real improvement (NOT a duplicate of an existing skill or open_proposal): a. Draft a plan doc to ~/.claude/plans/<YYYY-MM-DD>-<slug>.md, 30–100 lines. Sections: Problem, Evidence (cite retro ids), Proposed change, Success signal. b. Show the user a 4–6 line summary. c. Ask explicitly: "Register this as an accepted experiment? (y/n)" d. ONLY on yes:

   ax retro plan \
     --slug=<kebab-slug> \
     --form=skill|hook|guidance|automation \
     --title="<short title>" \
     --hypothesis="<one sentence>" \
     --plan-path=~/.claude/plans/<file>.md \
     --evidence-retros=<retro:id1,retro:id2> \
     --confidence=low|medium|high

4. If the prompt resolves to "no change needed" or "duplicate of existing", say so out loud and move on.