--- name: Retrospective (工程复盘) description: 将刚完成的故障排查/开发经历总结为可复用经验。当用户说"复盘"或"retrospective"时立即调用，把踩坑教训沉淀为规则避免重犯。 when_to_use: 用户说"复盘"、"retrospective"、"postmortem"、"总结一下这次经历"、"记录这次教训"，或完成一次重大故障修复后主动触发。 version: 1.0.0 languages: 中文优先 ---

Retrospective — 工程复盘

核心理念

> 不记录的坑，一定会再踩。 复盘不是写报告，而是把临时踩过的教训变成永久的系统规则。

复盘的产出不是给人看的文档，而是给未来 AI 助手看的"避坑指南"——未来再遇到相似场景，它能一眼识别、不再重犯。

触发条件

• 用户说「复盘」「retrospective」「postmortem」「总结这次经历」「记录教训」
• 刚完成一次重大故障修复 / 线上事故处理 / 困难bug排查后，主动询问「要不要复盘？」

复盘四步法（R-C-E-P）

对每一次经历，必须按以下四步输出结构化经验：

Step 1: R — Reconstruct（还原现场）

极简时间线：用 3-5 句话说清「什么时间、发生了什么、影响多大」。不要写流水账。

格式：

📅 时间：YYYY-MM-DD HH:MM
🎯 现象：<一句话描述用户可见的异常>
💥 影响：<受影响模块/数据/用户>

Step 2: C — Cause（根因链）

不要只写"原因是X"，要写根因链——一层一层问"为什么"直到触达设计/架构层面。

格式：

🔍 根因链：
  1. 直接原因：<导致故障的直接错误/异常>
  2. 深层原因：<为什么这个错误会发生？>
  3. 架构/设计层原因：<为什么我们的系统没能防御这个错误？>

⚠️ 红线：根因链禁止停留在"网络抖动""外部API不稳定"这种甩锅外部的结论。必须追问："我们的代码为什么没有兜底/重试/熔断？"

Step 3: E — Fix & Evidence（修复与验证）

格式：

🔧 修复动作：
  - <改了哪个文件，加了什么逻辑>
  - <执行了什么命令（重装/重启/配置变更）>
✅ 验证结果：<具体数据，如"95/95 拉取成功"，而不是"问题解决了">

Step 4: P — Prevention（防复发——这是复盘的核心产出）

这是最重要的一步。 从根因链反推：未来如何让同类问题不再发生，或至少更早发现？

分三类沉淀：

P1. 代码/配置层修复（可执行的改动）

• 加了什么兜底/重试/熔断？
• 加了什么监控/告警/健康检查？
• 改了什么默认配置？

P2. 规则层沉淀（写入项目规则，约束未来行为）

• 是否要在 .trae/rules/superpowers.md 或项目文档里加一条铁律？
• 是否要在相关代码顶部加警告注释（⚠️ BEWARE 开头）？
• 是否要补充 checklist？

P3. 经验层沉淀（写入项目记忆/教训库）

• 这是一个模式吗？在其他地方有没有同类风险？
• 一句话经验法则（未来Bot看到什么场景应该立刻警觉？）

沉淀动作（MUST DO）

完成 R-C-E-P 四步后，必须执行以下沉淀动作（不是二选一，是都做）：

• 代码注释：在修复过的关键代码处加一行 # ⚠️ BEWARE: <什么坑> 注释，未来读代码的人（或AI）立刻看到
• 规则文件：如果是通用教训（不局限于某一行代码），追加到 .trae/rules/ 下合适的规则文件里的"踩坑记录"章节
• 口头总结：在回复用户时，输出 P3 的「一句话经验法则」列表，方便用户直观记住

输出格式模板

最终回复用户时严格按此格式：

## 🔄 复盘：<一句话标题>

**R - 现场**
<时间/现象/影响>

**C - 根因链**
<三层根因>

**E - 修复验证**
<做了什么、数据证明修好>

**P - 防复发**
- 🛡️ 代码层：<已做/待做>
- 📏 规则层：<已写入/待写入>
- 💡 经验层：
  - <一句话法则1>
  - <一句话法则2>
  - ...

经验法则写作要求

一句话法则必须满足：

• 短：不超过 30 字
• 可执行：不是"注意网络问题"，而是"外部HTTP调用必须加重试+超时+降级"
• 触发条件明确：未来遇到什么场景 → 必须做什么动作

✅ 好例子：

• "Python schedule 库连续运行超7天必僵死，所有调度守护进程必须每日03:00自重启"
• "py-mini-racer 的 dlsym 错误无法通过try-except捕获，会导致整个adata/akshare链崩溃，pip force-reinstall是唯一修复"
• "数据源优先级链至少要有3条路径，2条路径在外部API同时故障时必然全挂"

❌ 坏例子：

• "注意schedule库可能有问题"（太虚）
• "外部API不稳定要小心"（没有具体动作）
• "以后要多检查"（废话）

注意事项

• 复盘必须在修复验证通过后做，不要边修边复盘
• 禁止文过饰非：如果第一次修复没修好、走了弯路，必须如实记录"第一次以为是X，修了没用，后来发现是Y"
• 禁止堆字数：复盘追求简短犀利，不是写论文。每个Step最多5行
• P3 经验法则是核心价值，其他都是铺垫。如果P3写不出新东西，说明复盘没做到位