retro

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Run a retrospective on:

$ARGUMENTS

(empty = this conversation).

Load config first. Read every

docs/agents/*.md

that exists — each one is a place a lesson can land. If none exist, still run the retro, but a lesson whose fix is "record this in config" becomes "run

/setup-project-skills

, then record it".

The point of a retro is that the next session doesn't repeat this one. A lesson that lives only in prose has to be read and remembered to help; a lesson that lives in structure (a type, a test, a gate) helps whether anyone remembers it or not. So every lesson is pushed as far up the ladder below as it will go.

对以下内容执行回顾：

$ARGUMENTS

（为空则表示当前会话）。

首先加载配置。 读取所有存在的

docs/agents/*.md

文件——每个文件都是经验教训可以落地的位置。如果不存在这类文件，仍然执行回顾，但对于修复方案为“将其记录到配置中”的经验教训，需调整为“运行

/setup-project-skills

，然后记录”。

回顾的意义在于让下一次会话不再重蹈覆辙。仅存在于文字描述中的经验教训需要被阅读和记住才能发挥作用；而存在于结构中的经验教训（类型、测试、gate）无论是否有人记得都能生效。因此，每条经验教训都要尽可能往下方阶梯的上层推送。

Steps

步骤

Gather evidence. Read the session: this conversation, or the transcript the user names (Claude Code keeps them as
```
~/.claude/projects/<repo-slug>/*.jsonl
```
). Collect, with a short quote or reference for each:
- ```
FAILED
```
  reports from the checker, especially a cause that came back more than once, and any
```
/loop
```
  stop condition that fired.
- User corrections — "no", "don't", "actually", "I said", a reverted edit, a re-explained requirement.
- Questions the agent had to ask that the repo or config should have answered.
- Reviewer findings that recurred across cycles, when
```
/loop
```
  ran a reviewer.
Filter. Keep only lessons that would happen again in a fresh session on this repo. A typo, a flaky network call, or a one-time decision is not a lesson — drop it and don't list it.
Route each lesson to the strongest fix that would have prevented it. Try the rungs in order and stop at the first that applies:
1. Design change — make the mistake impossible: a type that rejects the bad value, an API that can't be called wrong, one module instead of two that must stay in sync.
2. Lint rule or test — make the mistake loud: a lint rule for a mechanical pattern, a regression test for a behavior. A
```
standards.md
```
  rule tagged
```
mechanical
```
  that the reviewer keeps flagging belongs here.
3. New gate in
```
quality-gates.md#gates
```
  — when a tool that already exists would have caught it but nobody ran it. Gates mirror CI, so the proposal must add the same check to CI; a local-only gate is a surprise later.
4. Config edit in
```
docs/agents/*.md
```
  — a wrong command, a missing
```
commit.rules
```
  limit, a status name, a standard the reviewer should know.
5. Skill text — last resort, when the lesson is about process and none of the above can hold it. If the skill belongs to an installed plugin, propose an upstream issue instead of editing the installed copy; the next update would overwrite it.
When a lesson lands below rung 1, say in one clause why the stronger rungs don't fit. That clause is what keeps the ladder honest.

Propose. Show a numbered list, most valuable first:

1. <lesson in one line>
   evidence: <quote or reference>
   fix (<rung>): <the concrete change>
   files: <paths>

Then ask which to apply (

1,3

all

, or

none

). Nothing is changed before the user answers.

Apply only what was approved. Code changes (rungs 1–2) go through
```
stack.md#fix_agent
```
or the
```
builder
```
agent when installed, then
```
/verify-feature
```
— a new lint rule or test must fail on the old mistake and pass on the fixed code. Config and skill edits are made directly.
Report what was applied, what was declined, and whether anything is left uncommitted. Don't commit; offer
```
/finalize-feature
```
if the changes belong on the current branch.

收集证据。 读取会话内容：可以是本次对话，也可以是用户指定的会话记录（Claude Code 会将会话记录保存在
```
~/.claude/projects/<repo-slug>/*.jsonl
```
）。收集以下内容，每条都附上简短引用或参考来源：
- 检查器输出的
```
FAILED
```
  报告，尤其是重复出现的问题原因，以及任何被触发的
```
/loop
```
  停止条件。
- 用户纠正——比如“不对”、“不要”、“其实”、“我说的是”、被回退的编辑、被重新解释的需求。
- Agent 本应从仓库或配置中找到答案、却不得不向用户询问的问题。
- 当
```
/loop
```
  运行审查器时，跨周期重复出现的审查结果。
筛选。 仅保留在该仓库的全新会话中可能再次发生的经验教训。拼写错误、不稳定的网络调用或一次性决策不属于经验教训——直接丢弃，无需列出。
为每条经验教训匹配最强效的修复方案，即能够避免该问题再次发生的方案。按顺序尝试以下阶梯层级，停在第一个适用的层级：
1. 设计变更 —— 让错误根本不可能发生：比如用类型拒绝非法值，设计不会被错误调用的 API，用单个模块替代两个必须保持同步的模块。
2. Lint 规则或测试 —— 让错误显性化：针对机械性模式的 lint 规则，针对行为的回归测试。审查器反复标记的、带有
```
mechanical
```
  标签的
```
standards.md
```
  规则属于此类。
3. ```
quality-gates.md#gates
```
  中的新增 gate —— 当已有工具本可以发现问题但没人运行它时适用。Gate 与 CI 保持一致，因此提案必须将相同的检查添加到 CI 中；仅本地生效的 gate 会在后续带来意外问题。
4. ```
docs/agents/*.md
```
  中的配置编辑 —— 比如错误的命令、缺失的
```
commit.rules
```
  限制、状态名称、审查器应该知晓的标准。
5. Skill 文本 —— 最后手段，当经验教训属于流程类且上述所有方案都不适用时使用。如果该 Skill 属于已安装的插件，应提议提交上游 issue，而不是编辑已安装的副本；否则下次更新会覆盖修改内容。
如果经验教训落在第1层以下，需用一句话说明为什么更高层级的方案不适用。这句话是保证该阶梯规则合理的关键。
提案。 展示编号列表，按价值从高到低排序：
```
1. <lesson in one line>
   evidence: <quote or reference>
   fix (<rung>): <the concrete change>
   files: <paths>
```
然后询问用户要应用哪些修复（
```
1,3
```
、
```
all
```
或
```
none
```
）。在用户答复之前不做任何修改。
仅应用已批准的内容。 代码变更（第1-2层）需通过
```
stack.md#fix_agent
```
或已安装的
```
builder
```
Agent 执行，然后运行
```
/verify-feature
```
—— 新增的 lint 规则或测试必须在旧错误代码上失败，在修复后的代码上通过。配置和 Skill 编辑直接修改即可。
报告已应用的内容、被拒绝的内容，以及是否有未提交的修改。不要自动提交；如果修改应该合入当前分支，提供
```
/finalize-feature
```
命令选项。