hello-debug

---
name: hello-debug
description: 调试错误、修复 bug、排查失败测试、处理异常行为，或代码行为与预期不符时使用。
---

调试相关工作必须遵循以下规范。

## 编码前
禁止未经根因分析直接修复。
先建立可运行、可重复、可判断的反馈循环；没有反馈循环，不直接猜原因或改代码。

## Git 作为记忆
每次调试前，先读取相关的 git 历史：
- `git log --oneline -20` 查看最近变更
- `git log --all --grep="revert"` 查看过去的失败回滚
- 如果发现之前已经尝试并回滚过类似修复 → 不要重复同样的方向

## 反馈循环优先

反馈循环是调试入口，必须能证明“问题出现 / 问题消失”：
- 优先写失败测试；不适合写测试时，用 HTTP 脚本、CLI 样例输入、浏览器脚本、请求 / 事件回放、最小验证脚本、差异对比或压力循环复现
- 循环要尽量快、稳定、断言具体症状，不用“没有崩溃”代替正确性
- 非确定性问题先提高复现率，记录触发次数、失败比例和关键条件
- 实在无法建立循环时，停止并说明已尝试方式，向用户请求日志、录屏、请求记录、环境访问或授权加临时观测点

## 四阶段调试法

### 1. 定位
- 完整读取错误信息（不截断、不猜测）
- 用反馈循环稳定复现问题（确定触发条件）
- 反向追踪数据流（从错误点向上游追溯）

### 2. 分析
- 找到类似的正常工作代码，对比差异
- 检查最近的变更（git log/diff）
- 识别所有隐含假设

### 3. 假设
- 形成 3-5 个按可能性排序的假设
- 每个假设必须可证伪：写清“如果原因是 X，那么改变或观测 Y 会出现 Z”
- 单变量测试（一次只改一个东西）
- 记录每次尝试和结果

### 4. 修复
- 先写失败测试复现 bug
- 实现最小修复（针对根因，不是症状）
- 验证修复有效且无回归

## 临时观测点
- 临时日志必须带唯一前缀，如 `[DEBUG-a4f2]`
- 禁止“到处打印再搜索”；每个观测点都要对应一个假设
- 收尾前搜索前缀，删除所有临时日志、临时验证脚本和实验文件；确需保留时移动到明确的 debug 目录并说明原因

## 卡住升级机制

连续修复失败时，按以下阶梯升级策略：

第 1-2 次失败：正常反思，调整修复方向
第 3 次失败：停止。3 次失败意味着可能是架构问题而非局部 bug。重新从根因分析开始，质疑当前方向是否正确
第 4 次失败：扩大范围——重读所有相关文件，审查 git 历史中的相关变更，检查是否有隐藏的依赖或副作用
第 5 次失败：必须与用户讨论。提出以下选项：
  1. 组合之前接近成功的尝试
  2. 尝试完全相反的方向
  3. 重构架构而非继续局部修补
  4. 重新定义问题

超过 5 次：停止自主尝试，转为用户决策。

## 交付检查
- [ ] 根因已识别并记录
- [ ] 已建立能证明问题出现 / 消失的反馈循环
- [ ] 有失败测试复现 bug，或已说明没有合适测试切入点并给出替代验证
- [ ] 单一修复针对根因
- [ ] 临时观测点和实验文件已清理
- [ ] 无回归引入