retro-meta

Original：🇺🇸 English

Translated

Deep retro of retros - investigation pass that surfaces improvements across older retros and the current ax setup. External AI agent drives the reasoning with high thinking enabled. Triggers when user says "deep retro", "investigate ax", "what should I fix in my setup", "retro of retros", or invokes /ax:retro-meta. Use after `ax:retro` if proposals are sparse or you want broader exploration.

2installs

Sourcenecmttn/ax

Added on2026-08-27

NPX Install

npx skill4agent add necmttn/ax retro-meta

SKILL.md Content

View Translation Comparison →

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

bash

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

:

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
Reason about a candidate improvement. Use a high thinking budget - the point is to see what the heuristic missed.
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:
bash
```
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
```
If the prompt resolves to "no change needed" or "duplicate of existing", say so out loud and move on.

Step 4 - Optional: hand off to scaffolder

For each plan you registered, you may run:

bash

ax improve accept --with-agent <dedupe_sig>

This spawns the internal scaffolding agent to draft an artifact (SKILL.md, hook script, etc) from the plan. Skip if the plan is already self-sufficient.

Step 5 - Summary

Print one paragraph:

N plans registered, M of those scaffolded
V verdicts locked (with kind, e.g. "2× ignored, 1× adopted")
K open_proposals reviewed (and their disposition)
Any prompts that resolved to "nothing here"
Suggested next retro window

Anti-patterns

NEVER register a plan without an explicit user yes per plan. The human is the final filter.
NEVER auto-accept all open_proposals - the heuristic surfaces them but the deep pass exists precisely to triage them by reasoning, not by frequency rank.

NEVER write directly to

~/.claude/skills/

. Use

ax retro plan

+

ax improve accept --with-agent

.

NEVER skip Step 2's duplicate check. Proposing a Pre-Bash guard when one is already accepted just wastes the user's time.
Don't trust frequency alone. A frequency=1 retro can still be load-bearing if it represents a category Claude can't get right.
NEVER propose a new improvement that overlaps a pending experiment. Vet that one first - lock its verdict or escalate before piling on more proposals in the same area. The retrospective loop is incomplete if old experiments stay in limbo.

CLI reference

bash

# Snapshot only (no side effects)
ax retro meta --since=30 [--limit-retros=50] [--pretty]

# Register a user-approved plan as accepted proposal + experiment
ax retro plan \
  --slug=<kebab> \
  --form=skill|hook|guidance|automation \
  --title="<title>" \
  --hypothesis="<hyp>" \
  --plan-path=<path-to-plan.md> \
  [--evidence-retros=retro:a,retro:b] \
  [--artifact-path=<path>] \
  [--confidence=low|medium|high] \
  [--frequency=<N>] \
  [--json]

# Optionally hand off scaffolding to the internal agent
ax improve accept --with-agent <dedupe_sig>

# Lock the verdict on a previously-accepted experiment
ax improve verdict --set=adopted|ignored|regressed|partial|no_longer_needed <dedupe_sig>

Output of

ax retro meta

defaults to JSON because the reader is you, not a human.

retro-meta

NPX Install

Tags

SKILL.md Content

ax:retro-meta - deep retro of retros

When to fire

Prerequisites

Workflow

Step 1 - Snapshot

Step 2 - Vet existing experiments FIRST

Step 3 - Walk the investigation prompts (high thinking)

Step 4 - Optional: hand off to scaffolder

Step 5 - Summary

Anti-patterns

CLI reference