retro-meta

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ax:retro-meta - deep retro of retros

ax:retro-meta - 回顾会议的深度回顾

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.

作为

ax:retro

的配套功能，

ax:retro

会逐一展示基于启发式生成的建议，而

retro-meta

则会提出这样的问题：现有流程尚未发现哪些改进点？

本功能由外部Agent（即当前使用的Claude Code或开启深度思考模式的Codex）驱动推理。CLI仅负责生成结构化证据，并将用户批准的计划反馈回去。

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".

仅支持显式触发：

"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
```
斜杠命令
```
ax:retro
```
完成后，若用户希望进行更广泛的探索

请勿在用户发出“查看近期工作”这类通用指令时自动触发。

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.

```
ax
```
（axctl）已添加至PATH。若
```
ax doctor
```
执行失败，请停止操作并引导用户查看
```
docs/development.md#setup
```
（DuckDB动态链接库设置 - 无需守护进程）。
过去30天内至少有3次回顾会议。若少于此数量，调查依据不足，建议先使用
```
ax:retro
```
。

Workflow

工作流程

Step 1 - Snapshot

步骤1 - 生成快照

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.

bash

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

读取

/tmp/ax-meta.json

，重点关注以下键值：

experiment_status[]

- 优先读取此项（见步骤2）。每个条目包含：

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

。未锁定结论的条目（

locked_verdict=null

）排在最前面。

```
retros[]
```
- 每次会议的原始
```
tried/worked/failed/next
```
记录。
```
patterns.tool_failures
```
- 按
```
total_count
```
降序排列的工具故障模式。
```
patterns.corrections
```
- 总数 + 单会话最大值 + 会话数量。
```
patterns.friction_kinds
```
- 跨会话反复出现的摩擦类型。
```
current_state.skills
```
- 已安装的技能（请勿重复建议）。
```
current_state.open_proposals
```
- 现有启发式生成的建议。
```
current_state.accepted_experiments
```
- 已接受但结论待定的实验。
```
current_state.claude_md_user
```
/
```
claude_md_project
```
- 指导文件路径（若不存在则为null）。
```
investigation_prompts[]
```
- 必须逐一处理的调查提示。

Step 2 - Vet existing experiments FIRST

步骤2 - 优先审核现有实验

Walk

experiment_status

in order. For each entry with

locked_verdict=null

a. If

latest_checkpoint.suggested

ignored

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

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

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.

按顺序处理

experiment_status

中的条目。对于每个

locked_verdict=null

的条目：

a. 若

latest_checkpoint.suggested

为

ignored

或

regressed

：调查原因（读取

artifact_path

，抽样查看匹配的机会点），然后执行

ax improve verdict --set=<v> <proposal_dedupe_sig>

锁定结论。 b. 若

latest_checkpoint.suggested

为

adopted

且

days_since_accepted > 30

：将其锁定为

adopted

，避免占用开放列表空间：

ax improve verdict --set=adopted <proposal_dedupe_sig>

。 c. 若

latest_checkpoint

为null或

suggested

为

partial

：保持开放状态。在最终总结中注明该实验仍在收集数据。

参考

investigation_prompts

中的经验法则：若t+30天后

address_ratio < 0.1

，默认锁定为

ignored

，除非工件中存在明显的“尚未验证”理由。

Step 3 - Walk the investigation prompts (high thinking)

步骤3 - 处理调查提示（深度思考）

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.

对于

investigation_prompts

中的每一个提示：

通过Read/Glob/Grep检查相关状态：
- ```
~/.claude/skills/
```
  和
```
~/.agents/skills/
```
  中的技能文件
- 若
```
claude_md_user
```
  不为null，查看该文件
- 若
```
claude_md_project
```
  不为null，查看该文件
思考候选改进方案。使用充足的思考预算——本功能的核心就是发现启发式方法遗漏的点。
若确定存在真实改进（不是现有技能或开放建议的重复）： a. 将计划文档写入
```
~/.claude/plans/<YYYY-MM-DD>-<slug>.md
```
，篇幅30–100行。包含章节：问题、证据（引用回顾会议ID）、提议的变更、成功指标。 b. 向用户展示4–6行的摘要。 c. 明确询问：“是否将此注册为已接受的实验？(y/n)” d. 仅在用户回答“是”时执行：
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
```
若提示得出“无需变更”或“与现有内容重复”的结论，直接告知用户并继续处理下一个提示。

Step 4 - Optional: hand off to scaffolder

步骤4 - 可选：移交至脚手架工具

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.

对于每个已注册的计划，您可以执行：

bash

ax improve accept --with-agent <dedupe_sig>

此命令会启动内部脚手架Agent，根据计划生成工件（SKILL.md、钩子脚本等）。若计划已足够完善，可跳过此步骤。

Step 5 - Summary

步骤5 - 总结

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

打印一段总结：

已注册N个计划，其中M个已移交至脚手架工具
已锁定V个结论（注明类型，例如“2个标记为ignored，1个标记为adopted”）
已审核K个开放建议（及其处理结果）
哪些提示得出“无改进点”的结论
建议的下一次回顾周期

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.

绝对不要在未获得用户针对单个计划的明确同意时注册计划。人类是最终的筛选者。
绝对不要自动接受所有开放建议——启发式方法生成这些建议，但深度回顾的核心正是通过推理而非频率排名来筛选它们。

绝对不要直接写入

~/.claude/skills/

。请使用

ax retro plan

ax improve accept --with-agent

。

绝对不要跳过步骤2的重复检查。若已接受Pre-Bash防护，再次提出相同建议只会浪费用户时间。
不要仅依赖频率。即使频率为1的回顾会议，若代表Claude无法解决的类别，也可能至关重要。
绝对不要提出与待处理实验重叠的新改进点。请先审核该实验——锁定其结论或升级处理，再在同一领域添加更多建议。若旧实验一直处于待定状态，回顾循环就是不完整的。

CLI reference

CLI参考

bash

undefined

bash

undefined

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

可选：将脚手架工作移交至内部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.

ax improve verdict --set=adopted|ignored|regressed|partial|no_longer_needed <dedupe_sig>


`ax retro meta`的输出默认为JSON格式，因为其读取者是您（Agent）而非人类。