session-retrospective
会话结束时给工作流做一次只读复盘:只提取真实发生的系统性问题——需纠正的错误答案、跳过的闸门、错误路由、MCP 错误、skill/文档缺口、多轮纠正——并以字段枚举校验的 JSONL 条目追加到本地反馈日志:同一问题复发即规则缺口,优先级自动升级;无事记一条 success,绝不编造。说一句"开始修复"即进入修复模式:按复发与优先级排序逐项出修复预案,一项一确认后执行,每项回写闭环条目保持 append-only 可审计,且修复模式只凭日志即可跨会话运行。内置零依赖校验脚本(Node 18+):写入后与修复前机器校验日志健康度与复发分组。与复盘报告类技能互补:本技能是机器可聚合的信号数据层,不是给人读的报告。已对真实会话完成主路径与损坏行异常双场景冒烟。触发词:"回顾一下这个会话"、"记录会话反馈"、"会话复盘"、"根据反馈日志修复"、"开始修复"、"session review"、"log session feedback"、"retrospective"。
会话回顾
用本技能回顾当前会话,并把结构化反馈条目追加到项目的工作流反馈日志。
快速目录
- 会话结束想直接记:分析什么 → 如何写反馈(含 JSONL 字段表)→ 快速参考
- 拿不准某情况记不记:快速参考表(含两种"不记"情形)与回顾反模式
- 出了状况:异常场景速查(SR-E01 ~ SR-E05)
- 想修复:修复模式(可选第二阶段)
- 想看完整示例:references/retrospective-example.md
其余章节按需查阅:回顾铁律 / 反馈存到哪里 / 何时使用 / 何时不用 / 自动检查 / 规则 / 回顾完成检查清单 / 常见问题。
回顾铁律
三条不可违反的规则,违反任意一条都会让反馈日志失去价值:
- 不编造对话事实。 每条反馈必须指向会话中真实发生的轮次——AI 确实答错、闸门确实被跳过、工具确实报错。想不起来的不写,宁可少写。
- 只记录系统性信号。 一条反馈的价值在于指向可修的 skill/文档/规则缺口。纯执行失误(用户忘给参数、打字错误)没有修复目标,不写。
- 不记录秘密。 notes 里不出现令牌、密钥、密码、内网地址、完整报文。日志是给未来的改进决策读的,不是泄露源。
反馈存到哪里
默认位置:当前项目根目录下的 metrics/workflow-feedback.jsonl。如果项目设定了其他日志位置(查看项目文档或已有日志文件),用那个。首次写入时创建文件;它是只追加的本地状态,绝不提交到 git——首次写入时若 metrics/ 未被 git 忽略,提醒工程师把它加入 .gitignore。
何时使用
- 工程师说"回顾一下这个会话"、"记录会话反馈"或"session review"
- 任何工作流任务的工作会话结束时
- 解决了一个需要多轮来回的问题之后
- 工程师说"根据反馈日志修复"、"处理反馈"或"开始修复" → 直接进入修复模式
何时不用
- 会话刚开始、还没有可回顾的实质内容 → 说明情况,不生成空条目
- 整场会话只有琐碎澄清、无工作流问题 → 写一条
success即可,不做过度分析 - 工程师只想要对话摘要而非工作流反馈 → 那是总结任务,不是本技能
分析什么
回顾对话并识别:
- 需纠正的错误答案 — AI 给出了错误输出,工程师不得不纠正
- 跳过闸门 — 跳过了必需的工作流阶段或确认
- 错误路由 — AI 使用了错误的技能、工作流或方法
- MCP 错误 — 工具调用失败或阻塞了工作流
- 技能/文档缺口 — 因为规则缺失或不清晰而需要反复澄清
- 多轮纠正 — 需要 2+ 轮交流才能得到正确答案(同一问题的多轮纠正合并为一条,并注明轮次数)
- 成功完成 — 值得作为正面信号记录
每个独立问题写一条反馈条目。如果没有出错,写一条 success 条目。
如何写反馈
向反馈日志每行追加一个 JSON 对象:
{"timestamp": "2026-11-13T14:30:00+08:00", "platform": "claude", "area": "review", "result": "corrected", "issue_type": "wrong-routing", "priority": "medium", "notes": "<出了什么问题,正确行为应该是什么>", "ref": "PR-123"}
| 字段 | 取值 |
|---|---|
timestamp | ISO-8601 本地时间 |
platform | claude, codex, codebuddy, cursor, trae, github-copilot, intellij-copilot, gemini, opencode, other |
area | planning, implementation, review, git-pr, mcp, environment, docs, other |
result | success, blocked, corrected, failed |
issue_type | none, gate-skipped, wrong-routing, mcp-error, skill-sync-missing, generated-code-hygiene, logging-convention, utility-reuse, title-format, ticket-field, auth, tool-error, other |
priority | 可选:low, medium, high — 影响范围 × 复发频率;缺省视为 low,success 条目通常省略 |
notes | 出了什么问题,正确行为应该是什么 |
ref | 可选的工单 / PR 编号 |
从当前 AI 工具推断 platform,除非工程师另行指定。
复发标注: 追加前扫一眼已有日志——同一 area + issue_type 且问题实质相同才算复发:notes 末尾加 recurring(第N次),且 priority 至少 medium。仅枚举组合相同但问题实质不同的,按新问题记录——误升级会污染信号。复发是规则缺口的 strongest signal。「问题实质相同」的操作口径:同一类规则缺口作用在同一对象上——同一 skill、同一文档或同一流程环节;换对象或换缺口类型即为新问题。
自动检查
可靠的日志靠校验而非自觉。环境可运行 Node ≥ 18 时优先用内置脚本做机器校验;无 Node 时按下述三道检查逐条执行,效果等同:
- 写入前校验:条目组装后、追加前,先核对本轮全部条目——JSON 可解析、platform/area/result/issue_type/priority 全部通过枚举、notes ≤ 200 字符且不含秘密;不过就先修再写。
- 写入后确认:追加完成后重新读取日志,确认新增行确实落盘且可解析;若因编码或截断损坏,不重写原行(append-only),当场报告并按 SR-E05 追加更正条目。
- 修复模式全量校验:进入修复模式加载日志时,先逐行做 JSON 解析 + 枚举 + notes 长度检查,统计损坏行数(SR-E04)与各
area+issue_type的复发计数——计数结果直接作为修复排序依据,不靠印象。
机器校验脚本(零依赖,Node ≥ 18):
node scripts/validate-feedback.mjs metrics/workflow-feedback.jsonl
一次完成全部三道检查:逐行 JSON 解析 + 字段枚举 + notes 长度、敏感信息扫描(常见密钥/令牌模式命中即硬错误——铁律 3 的机器版)、完整 ISO-8601 校验(需含时区偏移与真实日期)、损坏行统计、复发候选分组(脚本按 area + issue_type 配对统计,配对相同不等于问题实质相同——是否复发由你按「问题实质相同」口径确认后再标 recurring)、按次数输出修复排序建议。退出码 0 = 日志健康(候选提醒不影响退出码),非 0 = 有硬错误——写入后与修复模式加载时各跑一次。
快速参考
| 情形 | 动作 |
|---|---|
| AI 答错、工程师纠正 | 每个独立问题一条 result=corrected |
| 跳过必需阶段/确认 | 一条 gate-skipped |
| 用错技能、工作流或方法 | 一条 wrong-routing |
| MCP/工具调用失败 | 一条 mcp-error 或 tool-error |
| 因规则缺失反复澄清 | 一条对应缺口的 issue_type |
| 2+ 轮才答对 | 合并为一条,注明轮次数 |
| 任务顺利完成 | 一条 success |
| 用户忘给参数、打错字 | 不记(无修复目标) |
| 用户单纯夸奖 | 不记(除非揭示了某条规则缺失) |
规则
notes控制在 200 字符以内,聚焦工作流中应该改变什么- 不要记录琐碎澄清(例如用户只是忘了提供的缺失参数)
- 聚焦系统性问题:表明 skill、文档或工作流规则需要更新的事情
- 不要提交反馈日志——它是只追加的本地状态
异常场景速查
| 码 | 场景 | 处理 |
|---|---|---|
| SR-E01 | 日志文件/目录不可写 | 首次写入先自动创建 metrics/ 目录;瞬时失败重试一次;仍不可写则报告原因,把条目内容打印到对话让工程师手动保存;绝不改写其他位置 |
| SR-E02 | 无对话可回顾(刚开会话就被调用) | 说明"没有可回顾的会话历史",不生成空条目或编造 |
| SR-E03 | 会话中途被调用 | 只回顾到当前为止,声明"回顾截至于当前轮次",提示会话结束后可再回顾一次;条目正常记录 |
| SR-E04 | JSONL 文件存在但部分行损坏 | 不重写、不删除损坏行;跳过并在汇总表报告"发现损坏行 N 条",追加从新行开始 |
| SR-E05 | 工程师不认可已记录的某条目 | 不删除(append-only);新增一条更正条目,notes 指向被更正条目的时间戳 |
回顾反模式
发现自己在做以下事情时,立即停下:
| 你在做/想的事 | 实际含义 | 正确做法 |
|---|---|---|
| 记录"用户没给参数"这类琐碎澄清 | 没有修复目标 | 按快速参考表跳过 |
| 把用户夸奖记成 feedback | 不是工作流问题 | 仅当它揭示规则缺失才记录 |
| notes 写成小作文 | 超过 200 字符无法消费 | 一句话问题 + 一句话正确行为 |
| notes 里带令牌/密钥/完整报文 | 泄露风险(铁律 3) | 脱敏后记录 |
| 同一问题每轮各记一条 | 刷屏掩盖复发信号 | 合并为一条并标注 recurring |
| 编一条"看起来该有"的反馈 | 日志失去可信度(铁律 1) | 宁缺毋滥,删掉它 |
回顾完成检查清单
输出汇总前,逐项确认:
- 每条反馈对应真实发生的对话轮次(可追溯,无编造)
- 无琐碎澄清、无夸奖式条目
- notes ≤ 200 字符且不含秘密/完整报文
- 同一问题的多轮纠正已合并(recurring 标注复发)
- 每行 JSON 通过字段枚举校验(platform/area/result/issue_type/priority)
- 追加后已重读日志,确认新增行落盘且通过校验(或
validate-feedback.mjs退出码为 0) - 反馈日志未被提交到 git(metrics/ 已忽略或已提醒)
- 文档独立安装可用:无跨技能相对路径,skill 内引用(references/)已验证存在
- 无事发生时写了一条 success
写完反馈之后
打印一张简要汇总表:
| 区域 | 问题类型 | 优先级 | 备注 |
|---|---|---|---|
| ... | ... | ... | ... |
然后根据发现的问题,建议当前项目中哪些文件可能需要更新——这是反馈闭环的下半段:日志记下信号,文件建议把它变成行动。工程师说一句"开始修复"即可进入修复模式,把建议变成已确认的改动(见下节)。
完整的真实回顾示例见 references/retrospective-example.md。
修复模式(可选第二阶段)
回顾阶段保持只读 + 追加日志;修复是显式的第二步。工程师说"根据反馈日志修复"、"处理反馈"或回顾刚结束时说"开始修复"时进入。
为什么独立成阶段
回顾若混入修复,测量就会被修改污染——日志的可信度建立在回顾阶段不动任何规则之上。分开后还有一个额外收益:修复模式只凭日志即可工作,不需要原对话,可以在一个全新的会话里跨会话执行。
修复流程
- 读取日志并全量校验:加载反馈日志,按「自动检查」逐行校验并统计复发计数;损坏行按 SR-E04 跳过并报告。可运行
node scripts/validate-feedback.mjs <日志路径>一步完成(含修复排序建议)。 - 排序:带
recurring标注的条目最优先,其次按priority(high → medium → low),同级按时间新者在前。 - 逐项出预案:每个条目先给出修复预案——目标文件、具体改动、为什么这样改——一项一确认,绝不批量盲改。notes 过简、背景不足时不凭猜测出预案,先向工程师确认缺失背景再提。
- 执行:工程师确认后执行改动;不确认就跳过,不强推。
- 闭环回写:每修复一项,向日志追加一条
result=success的闭环条目,notes 写明"已修复:<原条目时间戳>"——日志保持 append-only,修复历史可审计。
修复防护
| 情形 | 处理 |
|---|---|
条目无明确修复目标(success、纯观察) | 跳过并在汇总中说明 |
| 单条 low 级且非复发的观察 | 不直接改规则;提示工程师是否升级处理 |
| 修复方案会改动 skill 本体或团队级规则 | 必须给出可回滚的改动方式(如独立 commit),提示工程师评审 |
同一 area+issue_type 的复发条目 | 修复时一并核查该组全部历史条目,确认根因一致再动手 |
修复完成
输出汇总:已修复 N 项(对应哪些日志条目)、跳过 M 项及原因、剩余未处理项的优先级清单。
推荐搭配
以下搭配均为可选,本技能对它们无硬依赖:
- 定时/调度工具(平台 cron、schedule 类自动化):本技能不自我触发,会话结束时人工或工作流触发;要定时回顾,用调度工具在固定时间调用本技能的触发词即可。
- workflow-skill-designer(同仓库元技能):当日志反复出现"缺少某个工作流/技能"类缺口时,可结合它把修复模式确认的需求设计成 orchestrator + phases 结构化 workflow skill。
- 经验沉淀/记忆类技能(把通用经验晋升到 AGENTS.md 等工作区文件的那一类):本技能的日志是它们的输入——它们消费结构化信号做经验晋升与持续改进,本技能只负责把信号记准。
- 报告类复盘技能(结构化模板、复盘引导类):需要可追溯的轮次证据与信号统计时,本技能的日志可直接作为数据源。
常见问题
Q: 为什么不把反馈日志提交到 git? A: 它是本地工作状态,包含开发过程的试错细节,提交会把个人工作流噪音带进团队仓库。工程师可自行决定是否归档。
Q: 记错了怎么办? A: 日志是 append-only,不删除——新增一条更正条目,notes 指向被更正条目的时间戳(见 SR-E05)。错误的记录 + 更正本身也是一条工作流信号。
Q: 日志越积越大怎么办? A: 本技能只负责追加。体量影响读取时由工程师决定归档或清理策略;recurring 标注会帮助识别哪些模式已被吸收进规则、可以归档。
Q: 修复模式会未经确认改我的文件吗? A: 不会。逐项出修复预案、一项一确认;每项修复都回写一条闭环条目指向原条目时间戳,日志保持 append-only 可审计。修复模式只凭日志即可跨会话执行。
Q: 和经验沉淀/自我改进类技能是什么关系? A: 定位互补:它们面向持续学习、把通用经验晋升到 AGENTS.md 等工作区文件;本技能专注会话级工作流问题的结构化提取。本技能的日志输出可以直接被它们当作输入消费。
语言支持
本技能支持中英文交互。触发词包括"回顾一下这个会话"、"记录会话反馈"、"会话复盘"、"根据反馈日志修复"、"开始修复"、"session review"、"log session feedback"、"retrospective"、"start fixing"。notes 用会话的主要语言记录。
- Downloads
- 123All time
- Security audit
- Pass
- Last updated
- 5d ago
- Current version
- v1.0.5
- License
- MIT-0
