retro

用途

retro 是一个针对编码会话的复盘技能。它检查一次真实的编码会话，提出对智能体环境的改进建议，而不是改动产品代码。目标是让下一次运行更容易导航、更不容易出错。

该技能是人在回路的：先呈现发现，在用户选择要应用哪些发现之前，不修改引导文件、标准、钩子、CI 或技能。

何时使用

一次编码会话异常冗长、混乱或容易出错。
用户要求复盘最近的智能体会话。
一个 bug 或重复出现的错误暗示缺少某道护栏。

默认目标是当前会话。如果用户指定了数量或日期范围，则检查该确切范围。如果会话历史不可用，应说明这一点，并只审查仓库证据。

资料来源

在判断之前先阅读真实来源：

会话记录和工具输出，在可用时使用会话搜索。
AGENTS.md、CLAUDE.md、GLOSSARY.md、GLOSSARY-MAP.md 以及仓库本地的引导文件。
CODING_STANDARDS.md 或同等的审查指引。
现有的 package.json、pyproject.toml、Makefile、任务运行器、钩子和 CI 工作流。
最终 diff、测试输出以及任何未解决的警告。

不要从一行可疑代码推断出重复错误。每一条发现都必须与会话或仓库中的具体证据挂钩。

审查视角

按严重程度和预期杠杆排序发现。对每条发现记录：

Finding：发生了什么
Evidence：会话消息、命令、文件或 diff
Prevention：能阻止它的最小环境变更
Owner：仓库检查 | 智能体技能 | 引导文件 | 工具 | 文档
Cost：维护成本和误报风险

检查以下类别：

技能学习循环

把人工纠正当作工作流的训练数据，而不是一次性偏好：

在编辑之前保存智能体的输出。
针对相同输入制作并保存人工编辑后的版本。
说明该编辑反映了技能未编码的什么决策。
将规则改写为决策过程，包括它不适用的情形。
重新运行原始输入，并将结果与编辑后的版本比较。

不要添加诸如“让它更好”这样含糊的规则，也不要盲目把每一次编辑都编码为通用指令。只保留在真实工作中站得住脚的经验。如果某条经验是机械且稳定的，优先使用 linter、测试、钩子或 CI 检查，而不是更多的文字说明。把共享规则放在主技能中，把特定上下文的规则放在链接的参考或风格文件中，以免技能无节制膨胀。

自动化检查

确定性的测试、linter、类型检查、pre-commit 钩子或 CI 作业能否捕获该错误？先阅读现有的检查命令。如果检查存在但未接入或已静默失效，应修复接线，而不是发明另一个检查。

机械性错误属于自动化范畴：禁用 API、必需文件位置、schema 形状、生成文件漂移、导入规则或格式化。一句“记得要做这件事”不是护栏。

编码标准

把 CODING_STANDARDS.md 保留给自动化无法裁决的判断性事项：跨文件一致性、设计契合度、上下文中的命名以及审查期望。把面向审查者的规则放在那里，而不是实现细节。

引导文件

移除无效建议，把详细流程移入技能或文档。保持 AGENTS.md 及同类文件简短、易于导航且信息密度高。检查是否有过时的名称，例如 CONTEXT.md；在该约定适用时，本仓库使用 GLOSSARY.md。

工具经济性

寻找重复的宽泛搜索、冗余读取、缺失的过滤条件，或用一条窄命令即可替代的高成本调用。只有当工具或脚本变更能降低重复成本且不隐藏重要输出时，才建议变更。

信息获取

找出智能体需要但无法获取的信息：日志、服务状态、只读 API 数据、测试夹具、schema 或架构说明。优先使用安全的只读访问和简洁的指引。

技能漂移

当已安装或现有技能反复需要纠正时，比较相同输入在旧版本和修订版本下的结果。把差异视为技能漂移的证据：用户的标准变了、技能描述不充分，或规则过于字面。记录最小的持久变更及其验证结果。

输出

按以下顺序呈现结果：

Keep：行之有效且应保留的做法。
High priority：有明确预防收益的具体变更。
Medium priority：有用但不阻塞的改进。
Do not change：推测性、噪声大或更适合人工处理的想法。
Smallest next step：用户可以批准的一两项变更。

对每个候选项，包含确切的目标路径和建议的补丁形态。不要静默应用。当用户批准时，一次只做一个聚焦的变更，运行相关检查，并报告结果。

反模式

不要把产品代码的重写当作复盘修复。
不要把每一次一次性失败都变成新规则。
在可以用确定性检查的地方，不要增加文字说明。
不要让 AGENTS.md 膨胀成流程手册。
不要在没有人工选择的情况下自动执行会编辑仓库的复盘。
不要在没有证据的情况下声称某项会话发现。

验证清单

检查了正确的会话或日期范围。
发现基于记录、diff 或仓库证据。
在提出新检查之前，阅读了现有检查和引导文件。
机械性违规被分配给确定性自动化。
判断性事项被分配给审查标准。
发现按严重程度和杠杆排序。
在提议技能变更时，人工编辑被记录为前后的证据。
提议的规则描述决策和边界，而不仅仅是期望的输出。
重新运行原始输入，以验证技能确实学到了该变更。
未经用户批准，没有应用任何环境变更。