# Retro Debugging

> Retro Debugging

- Skill: `kaixin1seu/retro-debugging` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kaixin1seu/retro-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kaixin1seu/retro-debugging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kaixin1seu (https://skillmd.com/u/kaixin1seu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kaixin1seu/retro-debugging

---


# retro-debugging — 调试复盘透镜

## 适用范围与边界

本 skill 覆盖排错过程、根因分析和修复质量评估。

**与其它 skill 的区分**：
- 调了什么代码/改了什么逻辑 → `retro-coding`
- 调试过程中发现的数据问题 → `retro-data`
- 调试暴露出的实验设计缺陷 → `retro-experiment`

**不适用场景**：简单的语法错误修复、已知问题的标准解决流程、配置调整。

## 评估维度

### 1. 根因分析路径
- 排查路径是否高效？（先验证最简单的假设，还是直接跳到了复杂的可能性？）
- 排查顺序是否合理？（先检查输入数据 → 再检查中间处理 → 最后怀疑模型/核心逻辑）
- 有没有在错误方向花太多时间？（排除了一个假设后，是否及时调整方向？）
- 最终根因是否被确认？（不是"改了之后好了"而是"验证过就是这个问题导致的"）

### 2. 排查效率
- 定位问题花了多长时间？是否比合理时间长？
- 有没有走弯路？（如果重来一次，排查顺序会怎么调整？）
- 是否使用了有效的调试工具/方法？（二分法定位、最小可复现案例、日志分析）
- 信息获取是否高效？（该搜的搜了还是凭猜测？）

### 3. 信息利用
- 错误信息是否被仔细阅读？（有没有看完整报错还是只扫了一眼？）
- 日志/中间输出是否被充分利用？
- 之前的类似问题是否被参考？（有没有查已有的 memory/issue？）
- 外部资源（StackOverflow、GitHub Issues）是否被搜索？

### 4. 修复质量
- 修复是针对根因还是症状？（治标还是治本？）
- 修复是否引入了新问题？
- 修复后是否验证了相关路径？（不只是修的那个 case，相关的 case 也测了？）
- 是否需要添加预防措施？（加测试、加检查、加日志？）

### 5. 预防与文档
- 这个 bug 是否可以被更早发现？（加一个 assertion？加一个检查步骤？）
- 是否需要更新文档/注释来防止类似问题？
- 是否需要加自动化测试？
- 其他人会不会犯同样的错误？如何防止？

## 常见反模式

| 反模式 | 检测信号 |
|--------|----------|
| 先怀疑最复杂的部分 | 一上来就怀疑模型/算法有问题，实际是数据/配置问题 |
| 试错式修复 | 不分析根因，改一个地方试一下，不行再改另一个地方 |
| 只看症状 | 修了表面问题但没找根因（如只处理了报错不处理产生报错的原因） |
| 孤立的修复 | 只修了当前 case，没检查相关 case |
| 不记录排查过程 | 找到根因了就开心地修了，忘了记录排查路径 |
| 过早求助/放弃 | 还没充分排查就下结论说"搞不定" |
| 跳过最简单的检查 | 花 2 小时排查复杂问题，最后发现是文件路径拼错了 |
| 修复引入回归 | 修了当前 bug 但没跑已有的回归测试，导致旧功能被破坏 |

## 已固化模式

| 模式 | 适用信号 | 验证 | 来源 |
|------|----------|------|
| （待复盘时自动追加） | | | |

## 关键追问

### 挑刺式（找改进空间）
- 从发现问题到定位根因，排查路径是什么？每一步的依据是什么？
- 如果重来一次，可以在哪一步更早发现问题？
- 有没有一个简单的检查能在下次防止整个问题？
- 根因如果没被修复，会在什么场景下再次出现？
- 这个 bug 是否暴露了一个系统性的弱点？（不止这一个地方可能有问题？）
- 排查过程中，有没有被错误的信息/假设误导？

### 正向式（找值得复用的）
- 这次排查过程中，哪个排查步骤/调试方法特别有效？能不能固化为排查流程？
  （信号：某个方法在本次定位中起了决定性作用、或者多次被用到都有效）
- 有没有某个信息源（特定日志、监控指标）在定位中起了关键作用，下次优先看它？
  （信号：这个信息源提供了其它途径得不到的诊断信息、直接指向了根因）
- 有没有哪个预防措施（assertion、检查步骤、日志）在本对话之前就被加了，在本次直接拦截了问题？

### 反证条件指引
对于"修复已完成"的判断，追问：**什么具体信号会说明修复不完整或引入了新问题？**
（引导写出可操作的反证条件——如"如果下游指标 X 出现异常波动"而非空洞的"如果出了问题"）