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.
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.
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?
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.
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.
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.
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.
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.
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
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.
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:
Run ax improve show <dedupe_sig> --json (or reuse the row from
step 1).
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.
Ask the user: accept, reject, or skip.
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."
Step 3 - Verdict review
For each experiment whose latest checkpoint is unlocked
(locked_verdict IS NONE), in age order:
Run AX_NO_AUTO_INGEST=1 ax improve verdict <dedupe_sig> to fetch the
experiment + checkpoint history.
When the current view carries a current_reason, there is no
suggestion to confirm. Report the reason as it is - no opportunities in the window, no detector for this form, retired - and move to
the next experiment. A suggestion in the checkpoints history is
history, not a recommendation.
Otherwise render the current checkpoint as 2-3 lines:
Schema change guardrail - +30s checkpoint
12 opportunities in window, 8 addressed (66%) - observed use.
Suggested: adopted.
Ask the user to confirm the suggested verdict OR override:
adopted (artifact is doing real work)
ignored (user wrote it but never invoked it)
regressed (it made things worse)
partial (mixed signal)
no_longer_needed (pattern self-resolved; trigger stopped firing)
Run ax improve verdict <dedupe_sig> --set <verdict> to lock it. All
five values stay available to the user by hand, including
no_longer_needed, which the algorithm never suggests on its own.
Step 4 - Hook effectiveness pass (optional)
Only run if the user asked for hook review OR if step-1 found ≥3
blocking errors. Light touch - this section is read-only.
Show top hooks from ax hooks summary --since=7 --tail=20 if not
already shown.
If a hook keeps blocking, ask: "Want to inspect a recent
invocation?" Then run
ax hooks invocations --command="<hook>" --tail=5 and render.
Backtest known feedback cases:
ax hooks cases enforce-worktree --tail=50 --window=3
Treat each backtest result as one case type. Report pass/fail/
inconclusive counts.
Interpretation:
- A blocking hook error is not automatically bad. If the next few
agent actions show corrected behavior, it's a useful corrective
signal.
- A successful hook is not automatically useful. Look for downstream
behavior change.
hook_progress without a terminal success/blocking event is a
telemetry gap unless correlated with visible behavior.
- Prefer deterministic backtests over model judgment.
- To author a NEW guard from a recurring failure:
ax hooks init, write a defineHook hook in ~/.ax/hooks/, ax hooks backtest it against history, then ax hooks install --providers=claude,codex.
Step 5 - Close out
Output a one-paragraph summary:
- Counts: accepted / rejected / skipped / verdicts locked.
- Any scaffolded SKILL.md files that still need refinement.
- When the next retro is recommended. Compute: earliest
experiment.created_at + 7d among accepted-but-unlocked
experiments, formatted as "next retro suggested around YYYY-MM-DD".
Then ask whether the user wants to commit the scaffolded skill files +
proposal-status changes (DB is local, but SKILL.md files are on disk
and may belong in version control).
How to track feedback
The retro itself produces durable signal that the experiment loop
already captures:
Acceptance rate by form - after the session, derive from
proposal.status. If skill-form gets accepted 80% but guidance gets
rejected 80%, the derive-proposals stage is over-eager on the wrong
form. Surface as an observation.
Reject reasons - proposal.reject_reason is a free-text corpus.
After the session run:
ax improve list --status=rejected --json | jq '.[].reject_reason'
Look for repeated phrases ("duplicate of existing hook"). When a
pattern emerges, the derive-proposals stage should dedupe against it
Verdict surprises - when the user overrides a suggested verdict,
note it. Repeated overrides mean the verdict math is biased.
These are observations, not actions. Report in the close-out; don't
write to insight tables.
CLI reference Claude calls
ax improve list [--form=skill|subagent|hook|guidance|automation] \
[--status=open|accepted|rejected|superseded|all] [--json]
ax improve show <dedupe_sig> [--json]
ax improve accept <dedupe_sig> [--force]
ax improve reject <dedupe_sig> --reason "<text>"
ax improve verdict [<dedupe_sig>] [--set <verdict>] [--json]
ax improve checkpoint [--force] # Step 1 prerequisite; --force only on request
ax improve reset --yes # destructive; only when user requests
ax retro pending [--since=N] [--idle-min=N] [--json] # Step 0 backlog
ax retro brief --session=<id> [--out-dir=<path>] [--json]
ax retro emit --session=<id> [--source=<src>] [--from-file=<json>]
ax retro list [--since=N] [--limit=N] [--json]
ax hooks summary [--since=N] [--tail=N]
ax hooks invocations [--command="<name>"] [--tail=N]
ax hooks cases <case-name> [--tail=N] [--window=N]
--force on accept overwrites an existing SKILL.md scaffold. Only use
when the user explicitly says so.
reset --yes wipes ALL proposal/experiment/checkpoint state. NEVER run
without explicit user confirmation in this session.
Failure modes
ax improve list returns empty → run ax ingest --derive-only once,
retry. If still empty, evidence is genuinely thin; tell the user.
ax improve accept reports scaffold_exists → ask the user if they
want --force or to abandon.
ax improve verdict --set reports verdict_locked → that experiment
is already finalized; show the locked value and move on.
ax improve checkpoint fails → measurement is unavailable for this
retro. Say so, skip Step 3, and keep Step 2 going.
ax hooks summary returns nothing → retry with --since=30; if
still empty, the hook telemetry pipeline is idle, surface as a TODO.
- Read/query error → tell the user to check
docs/development.md#setup
(AX_DUCKDB_DYLIB).
Anti-patterns
- Don't dump raw JSON. Render summaries.
- Don't run
ax improve accept for every open proposal in a batch; the
user must say yes per row.
- Don't write to
~/.claude/skills/ directly. The CLI handles that.
- Don't propose deleting a scaffolded SKILL.md mid-retro; that's a
separate cleanup task.
- Don't auto-implement experiments from the hook pass. Recommendations
only; the user decides + commits.
1---2name: retro3description: Guided experiment-loop retrospective over the ax agent-experience graph. Walks the user through their open proposals (accept-with-scaffold or reject), pending verdicts (confirm the suggested verdict or override), and recent harness-hook effectiveness signal. Triggers when the user says "let's do an ax retro", "ax retrospective", "review my ax proposals", "triage proposals", "experiment loop status", "lock pending verdicts", "hook effectiveness review", "intervention review", "self-improvement session", or invokes /ax:retro. Reads/writes via the local `ax improve` and `ax hooks` CLIs. Do NOT auto-trigger on unrelated work.4metadata:5 source: https://skillmd.com/skills/necmttn/retro6---78# ax:retro - guided experiment-loop session910Closes the self-improvement loop. Claude orchestrates `ax improve …`11commands; the user decides each row.1213Assumes `ax` (axctl) is on PATH. If `ax improve list` fails, tell the user14to check `docs/development.md#setup` (DuckDB dylib setup - no daemon15required) and stop.1617## When to fire1819ONLY fire on explicit triggers:20- "let's do an ax retro" / "ax retrospective" / "retro time"21- "review my ax proposals" / "triage proposals"22- "what's my experiment loop status" / "lock pending verdicts"23- "hook effectiveness review" / "intervention review"24- "self-improvement session"25- `/ax:retro` slash command (if the plugin marketplace publishes one)2627Do NOT fire on a generic "look at my recent work" - that risks dragging28unrelated context into the loop.2930## Defaults3132- Window for hook signals: last 7 days. Widen to 30 if evidence is sparse.33- Don't apply changes silently. Every accept/reject/verdict gets the34 user's explicit yes per row.35- The retro is read-mostly. Its side-effects are the Step 1 checkpoint36 measurements, the task briefs `accept` emits, and verdict locks.3738## Workflow3940### Step 0 - Drain pending session retros4142Before the proposal queue, check whether prior sessions still owe a43retro. This is the "quota arbitrage" path - idle Opus budget chews44through the backlog so the experiment loop has signal next time.45461. Run:4748 ```bash49 ax retro pending --since=7 --idle-min=30 --json50 ```5152 Returns sessions in the last 7 days that have no `reviewed` graph53 edge yet AND look finished (explicit `ended_at`, or last turn is54 >30min idle). If the list is empty, skip to Step 1.55562. Show the list to the user as 1 line per session (project · turns ·57 model · reason). Ask:5859 > N session(s) pending retro. Want me to dispatch the60 > retro-reviewer subagent for all of them in parallel, or pick a61 > subset?62633. On `all` or `<subset>`: for each chosen session, write a brief:6465 ```bash66 ax retro brief --session=<session_id>67 ```6869 This writes `.ax/tasks/retro/<key>.md` with frontmatter (transcript70 path, suggested model, turn count, etc.) and a body that tells the71 reviewer what to do.72734. Dispatch one `retro-reviewer` subagent per brief, in parallel. Pass74 each brief path in the prompt; let the subagent's frontmatter pin75 `model: opus` (override per session if `suggested_model` differs and76 the user asked you to economize).7778 If the `retro-reviewer` subagent type doesn't resolve (not installed,79 or the active harness is not Claude Code), read and review the brief INLINE80 using its required-output instructions instead of abandoning the backlog.81825. Wait for all subagents. Aggregate results: counts of retros emitted,83 proposals recommended, model-fit suggestions. Render as a short84 summary. The user does not approve retro emissions per row - the85 subagent already wrote them. The user DOES decide on resulting86 proposals in Step 2.87886. The `reviewed` edge now exists for each drained session, so a89 re-run of `ax retro pending` should show fewer rows.9091If the user declines Step 0, move on. The backlog stays - next retro92picks it up.9394### Step 1 - Snapshot9596Measure first, then read. The checkpoint pass is what turns due windows97into current ones; a verdict read taken before it reports whatever the98last run happened to leave behind.991001. Run the prerequisite ALONE and wait for it:101102 ```bash103 AX_NO_AUTO_INGEST=1 ax improve checkpoint --json104 ```105106 It reads the published snapshot and writes checkpoint judgments only -107 no transcript parsing, no guidance edits, no verdict locks. Leave108 `--force` out of an ordinary retro; it rewrites unreviewed windows that109 are already current.1101112. On success, run the reads (parallel is fine). Prefix EVERY command -112 a prefix on the first one leaves the freshness drive on for the rest:113114 ```bash115 AX_NO_AUTO_INGEST=1 ax improve list --status=open --json116 AX_NO_AUTO_INGEST=1 ax improve list --status=accepted --json117 AX_NO_AUTO_INGEST=1 ax improve verdict --json118 AX_NO_AUTO_INGEST=1 ax retro list --since=7 --json # cluster-derived friction summary119 AX_NO_AUTO_INGEST=1 ax hooks summary --since=7 --tail=20 # optional; tolerate failure120 ```1211223. If the checkpoint run fails, tell the user measurement is unavailable123 and continue with proposal review only. Any suggestion already stored124 belongs to an earlier run - report it as that, and skip the verdict125 step.1261274. If the checkpoint result reports `cacheRefreshRequired` above zero, the128 opportunity evidence needs deriving; say so, and treat those129 experiments as unmeasured. When the user asks for current evidence, run130 three operations in order, each awaited on its own: `ax ingest` (wait131 for successful publication), the checkpoint prerequisite, then the132 reads.133134`ax retro list` reflects three pattern types now:135- **tool failures** (skill form) -> `Pre-<Tool> guard` proposals136- **correction pressure** (guidance form) -> "Reduce recurring user137 corrections" proposals targeting `CLAUDE.md`138- **friction kinds** (skill form, one per kind) -> `Address recurring139 <kind> friction` proposals140141If any of those surfaced, mention them so the user knows to triage in142Step 2.143144Compute counts: open proposals (by form), accepted experiments with145`locked_verdict IS NONE`, and - separately - experiments whose current146view carries a `current_reason` (insufficient data or a lifecycle state).147Then render to the user as 2-4 lines, e.g.:148149> 7 open proposals (3 skill, 4 guidance). 2 accepted experiments are150> waiting on a verdict. Hook activity last 7d: 142 invocations, 3151> blocking errors. Want to triage proposals first, lock the pending152> verdicts, or skim hook signals?153154If both proposal/verdict queues are empty: tell the user nothing's due155and offer `ax ingest --derive-only` to refresh evidence.156157### Step 2 - Triage open proposals158159Order open proposals by `frequency` desc. For each, in turn:1601611. Run `ax improve show <dedupe_sig> --json` (or reuse the row from162 step 1).1632. Render as 3-5 lines. Example for a skill proposal:164165 > **Schema change guardrail** (skill · freq=9 · confidence=high)166 > Hypothesis: schema edits often surface in fix-chains within ~14d.167 > Trigger: fix commits overlap schema files.168 > Behavior: run schema lint + one read/write smoke before edit.1691703. Ask the user: **accept**, **reject**, or **skip**.1711724. Branch:173 - **accept** → run `ax improve accept <dedupe_sig>`.174 By default this emits a TASK BRIEF and returns its `task_path`; it175 does not install the artifact. Report that path.176 Offer: *"Want me to implement the brief now?"*177 If yes: implement it, then run `ax improve lint` so ax reconciles the178 marker it finds on disk and records the installed artifact. Until179 lint records one, the experiment has no measurable installation.180 - **reject** → ask for a short reason (≤80 chars).181 Run `ax improve reject <dedupe_sig> --reason "<reason>"`.182 - **skip** → no command. Move on; the proposal stays open for the183 next retro.184185After the loop, summarize: *"Accepted 3, rejected 1, skipped 2."*186187### Step 3 - Verdict review188189For each experiment whose latest checkpoint is unlocked190(`locked_verdict IS NONE`), in age order:1911921. Run `AX_NO_AUTO_INGEST=1 ax improve verdict <dedupe_sig>` to fetch the193 experiment + checkpoint history.1941952. When the current view carries a `current_reason`, there is no196 suggestion to confirm. Report the reason as it is - `no opportunities197 in the window`, `no detector for this form`, `retired` - and move to198 the next experiment. A suggestion in the `checkpoints` history is199 history, not a recommendation.2002013. Otherwise render the current checkpoint as 2-3 lines:202203 > **Schema change guardrail** - +30s checkpoint204 > 12 opportunities in window, 8 addressed (66%) - observed use.205 > Suggested: **adopted**.2062074. Ask the user to confirm the suggested verdict OR override:208 - `adopted` (artifact is doing real work)209 - `ignored` (user wrote it but never invoked it)210 - `regressed` (it made things worse)211 - `partial` (mixed signal)212 - `no_longer_needed` (pattern self-resolved; trigger stopped firing)2132145. Run `ax improve verdict <dedupe_sig> --set <verdict>` to lock it. All215 five values stay available to the user by hand, including216 `no_longer_needed`, which the algorithm never suggests on its own.217218### Step 4 - Hook effectiveness pass (optional)219220Only run if the user asked for hook review OR if step-1 found ≥3221blocking errors. Light touch - this section is read-only.2222231. Show top hooks from `ax hooks summary --since=7 --tail=20` if not224 already shown.2252262. If a hook keeps blocking, ask: *"Want to inspect a recent227 invocation?"* Then run228 `ax hooks invocations --command="<hook>" --tail=5` and render.2292303. Backtest known feedback cases:231232 ```bash233 ax hooks cases enforce-worktree --tail=50 --window=3234 ```235236 Treat each backtest result as one case type. Report pass/fail/237 inconclusive counts.2382394. Interpretation:240 - A blocking hook error is not automatically bad. If the next few241 agent actions show corrected behavior, it's a useful corrective242 signal.243 - A successful hook is not automatically useful. Look for downstream244 behavior change.245 - `hook_progress` without a terminal success/blocking event is a246 telemetry gap unless correlated with visible behavior.247 - Prefer deterministic backtests over model judgment.248 - To author a NEW guard from a recurring failure: `ax hooks init`, write a `defineHook` hook in `~/.ax/hooks/`, `ax hooks backtest` it against history, then `ax hooks install --providers=claude,codex`.249250### Step 5 - Close out251252Output a one-paragraph summary:253- Counts: accepted / rejected / skipped / verdicts locked.254- Any scaffolded SKILL.md files that still need refinement.255- When the next retro is recommended. Compute: earliest256 `experiment.created_at + 7d` among accepted-but-unlocked257 experiments, formatted as "next retro suggested around YYYY-MM-DD".258259Then ask whether the user wants to commit the scaffolded skill files +260proposal-status changes (DB is local, but SKILL.md files are on disk261and may belong in version control).262263## How to track feedback264265The retro itself produces durable signal that the experiment loop266already captures:267268- **Acceptance rate by form** - after the session, derive from269 `proposal.status`. If skill-form gets accepted 80% but guidance gets270 rejected 80%, the derive-proposals stage is over-eager on the wrong271 form. Surface as an observation.272- **Reject reasons** - `proposal.reject_reason` is a free-text corpus.273 After the session run:274275 ```bash276 ax improve list --status=rejected --json | jq '.[].reject_reason'277 ```278279 Look for repeated phrases ("duplicate of existing hook"). When a280 pattern emerges, the derive-proposals stage should dedupe against it281 - tell the user.282- **Verdict surprises** - when the user overrides a suggested verdict,283 note it. Repeated overrides mean the verdict math is biased.284285These are observations, not actions. Report in the close-out; don't286write to insight tables.287288## CLI reference Claude calls289290```bash291ax improve list [--form=skill|subagent|hook|guidance|automation] \292 [--status=open|accepted|rejected|superseded|all] [--json]293ax improve show <dedupe_sig> [--json]294ax improve accept <dedupe_sig> [--force]295ax improve reject <dedupe_sig> --reason "<text>"296ax improve verdict [<dedupe_sig>] [--set <verdict>] [--json]297ax improve checkpoint [--force] # Step 1 prerequisite; --force only on request298ax improve reset --yes # destructive; only when user requests299300ax retro pending [--since=N] [--idle-min=N] [--json] # Step 0 backlog301ax retro brief --session=<id> [--out-dir=<path>] [--json]302ax retro emit --session=<id> [--source=<src>] [--from-file=<json>]303ax retro list [--since=N] [--limit=N] [--json]304305ax hooks summary [--since=N] [--tail=N]306ax hooks invocations [--command="<name>"] [--tail=N]307ax hooks cases <case-name> [--tail=N] [--window=N]308```309310`--force` on `accept` overwrites an existing SKILL.md scaffold. Only use311when the user explicitly says so.312313`reset --yes` wipes ALL proposal/experiment/checkpoint state. NEVER run314without explicit user confirmation in this session.315316## Failure modes317318- `ax improve list` returns empty → run `ax ingest --derive-only` once,319 retry. If still empty, evidence is genuinely thin; tell the user.320- `ax improve accept` reports `scaffold_exists` → ask the user if they321 want `--force` or to abandon.322- `ax improve verdict --set` reports `verdict_locked` → that experiment323 is already finalized; show the locked value and move on.324- `ax improve checkpoint` fails → measurement is unavailable for this325 retro. Say so, skip Step 3, and keep Step 2 going.326- `ax hooks summary` returns nothing → retry with `--since=30`; if327 still empty, the hook telemetry pipeline is idle, surface as a TODO.328- Read/query error → tell the user to check `docs/development.md#setup`329 (`AX_DUCKDB_DYLIB`).330331## Anti-patterns332333- Don't dump raw JSON. Render summaries.334- Don't run `ax improve accept` for every open proposal in a batch; the335 user must say yes per row.336- Don't write to `~/.claude/skills/` directly. The CLI handles that.337- Don't propose deleting a scaffolded SKILL.md mid-retro; that's a338 separate cleanup task.339- Don't auto-implement experiments from the hook pass. Recommendations340 only; the user decides + commits.