/debug

问题诊断。当遇到 Bug、报错或异常行为时使用。

问题诊断

步骤

1. 收集信息

   • 读取报错信息/日志
   • 找到相关源代码
   • 检查最近的 git 变更（git log --oneline -10）

2. 定位根因

   • 从报错点沿调用链向上追踪
   • 检查输入数据是否符合预期
   • 检查是否有最近的代码变更引入了问题

3. 验证假设

   • 阅读相关测试用例，确认测试是否覆盖了出错场景
   • 如果有多个可能原因，按概率排序，逐一排查

4. 给出修复方案

   ## 根因
   [一句话描述]
   
   ## 修复方案
   [具体修改内容]
   
   ## 验证方法
   [如何确认修复有效]
   
   ## 防御措施
   [如何防止类似问题再次发生]

5. 等待确认后执行修复

6. 归档检查

   修复完成后，三问法评估：

   1. 花了超过 30 分钟才定位？
   2. 根因不在报错的直接指向？
   3. 同类问题可能在其他场景复发？

   任一为是 → 提示用户归档。确认后：

   • 生成 docs/troubleshooting/{YYYY-MM-DD}-{slug}.md（症状→根因→解法→防御，4 个章节）
   • 更新 docs/troubleshooting/README.md 索引表（按领域分类）
   • 如果 docs/troubleshooting/ 目录不存在则创建

   参考 doc-06 §4.2 Troubleshooting 格式契约

IMPORTANT：如果不确定根因，明确告知用户你的不确定性，不要猜测性地修改代码。