---
name: bug-debugging
description: 针对具体错误、失败测试、偶发异常或性能回归定位根因，并在用户确认修复方案后实施修复。适用于“排查这个 bug”“为什么这里失败”“修好这个异常”；不用于泛泛讲解报错含义、无具体症状的全仓找 bug 或仅评审 diff。
---

# Bug 调试与修复

把一个具体症状推进到有证据的原因、可审阅的方案，以及经用户同意并验证的修复。

```text
确认症状 → 复现或取证 → 验证根因 → 展示方案并等待同意
         → 实施修复 → 回归验证与清理
```

## 执行边界

- **修复前必须展示原因、证据、修复方案、影响与验证办法，等用户明确同意该方案后再实施。** “帮我修好”、紧急程度、沉默或调查子 agent 的建议，都不代表对尚未展示的方案的同意。
- 用户只要求诊断时，交付结论与建议；不把诊断自动扩展成修复。已有具体方案和明确批准时复用批准记录，不重复确认。
- 确认前可读代码、运行本地测试、分析日志，在临时目录或隔离副本中制作复现与做可撤销的实验；不把实验性补丁应用到用户工作区，不修改业务代码、持久配置或弱化测试来“试修”。若取证必须改动用户工作区或共享环境，先说明具体诊断操作并取得同意；诊断授权不等于修复批准。
- 委派给 `research` 或 `implementation-workflow` 时传递当前阶段与授权范围，不通过委派绕过确认点。部署、外发、生产写操作不随修复批准自动获得授权。

## 1. 确认症状与当前状态

读取项目指令、相关代码与测试及当前 Git 状态，保留用户已有改动。明确期望行为的依据、实际行为、触发输入、版本/环境、影响范围；已有信息直接复用，只追问阻止调查的缺口。

先确认这是用户报告的那个失败。构建失败、缺失依赖或无效测试命令应单独记录，不能当作目标 bug 的复现。期望行为存在产品歧义时，先明确约定，不能把个人偏好当缺陷。

简单问题可用一个复现和一个有依据的假设完成诊断；不为填流程强凑多个原因、多个子 agent 或长报告。

## 2. 建立复现或可核对的观测

优先复用失败测试、用户操作或现有脚本。记录实际执行的命令/操作、环境、输入和关键输出；断言应能区分期望行为与该症状，不能只检查“没报错”。读代码以构造复现是允许的。

按需缩小输入和执行路径，每次缩减后重跑，并保留原始场景；缩减到足以区分原因即可，不要求证明全局最小。复杂复现、偶发异常、性能回归及仅人工可见的症状，按需读 `references/reproduction-strategies.md`。

无法复现时继续利用已有日志、调用链和环境差异取证，明确缺失信号；不得伪造失败命令或把一次通过当作不存在缺陷。调查受阻时交付已知事实、已排除项及最有区分力的下一项取证需求，不用猜测填满结论。

## 3. 用实验验证原因

从症状沿数据或控制流向上追踪：输入与状态在哪里首次偏离约定，什么触发条件使偏差传到用户可见结果。堆栈末端的报错位置不一定是原因。

有多个合理解释时列出候选，逐一写清“依据 → 预测 → 验证方法”；每次只验证一个假设或改变一个关键变量，失败后更新结论，不叠加补丁。用正常对照或反证检查解释是否只是在迎合现象。复杂调用链、插桩与证据交接见 `references/evidence-and-tracing.md`。

根因结论标注：**已验证**（触发链与区分性实验相符）、**有证据支持**（证据吻合但关键环节未验证）、**未确定**（仍有竞争解释）。附可定位的源码/日志证据和实际实验结果；修补实验变绿本身不足以排除隐藏错误或错误断言。

`research` 可调查限定的调用链、版本行为或日志问题。主 Agent 复用其报告，只抽查决定根因和修复方向的关键证据；不完整重跑调查。版本变化、证据冲突或缺失时才补查对应部分。委派方式和返回契约见 `references/evidence-and-tracing.md`。

## 4. 提交方案，等待用户同意

向用户说明以下内容，按问题复杂度控制篇幅：

1. **原因与证据**：发生条件、因果链、根因状态，以及仍未验证的部分。
2. **推荐修复**：要改的模块和行为、为什么能解决问题；有实质取舍时说明替代方案。
3. **影响与风险**：兼容性、调用方、数据或性能影响，以及必要的回退办法。
4. **验证办法**：如何证明旧行为失败、新行为符合约定，并覆盖原始场景及相邻边界。

最后明确询问是否按该方案实施，并**停在待确认状态**。不能一边问一边修改，不能先完成用户工作区中的修复再请求追认。展示示例与续接契约见 `references/proposal-and-handoff.md`。

根因未确定时，提交下一项取证计划；若用户需要先止损，把缓解措施与根因修复分开说明，单独征求同意，不承诺已找到根因。

## 5. 获批后实施修复

确认回复对应已展示的具体方案及范围；用户提出异议或另一个方案时，先分析并更新方案。批准后只实现该方案，不重复请求相同授权。根因、对外行为、影响范围或迁移方式发生实质变化时，暂停受影响的实施，解释变化并重新确认；局部实现细节不构成重新审批理由。

在能够覆盖真实触发路径的层次补回归验证，先见目标失败，再做最小必要修复；可以把诊断用的复现提升为仓库测试。既有失败测试充分覆盖时直接复用，不额外造测试。测试入口不足时选择集成测试、重放或人工验证并说明限制，不为写单测擅自重构架构。

单文件低风险修改直接实施；跨模块改动或需要集成时使用可用的 `implementation-workflow`，传入原因、证据、批准范围和验收标准。它负责实施组织，本技能继续负责原始症状是否解决。无相关技能或委派能力时按同一契约自行执行。

修复无效时回到证据和假设，撤销自己的失败实验，保留用户改动。连续失败或实验不再产生新信息时，停止堆补丁并复查前提、复现有效性和模块边界；失败次数不能证明架构有问题。新方案超出原批准范围时重新确认。

## 6. 验证、清理与交付

- 重跑回归验证和**原始未最小化的场景**，检查受影响的正常行为；按改动风险运行项目要求的检查，不无目的扩大测试。
- 偶发与性能问题记录前后样本和测量条件；一次通过不能证明偶发缺陷消失。环境不可用或用户操作尚未验证时明确报告。
- 清理本次临时探针与无用副本，检查最终 diff；保留有效回归测试和用户改动。不要用整文件回滚覆盖用户工作。
- 汇报原因、批准方案的实际改动、执行的验证及未解决项。只有证据支持时才称“已修复”，区分“已改但未验证”“仅缓解”和“调查受阻”。

通常在对话中交付。复杂调查需卸载上下文或用户要求保存时，遵循目标仓库报告目录约定，复用已有报告目录，兜底 `docs/research/YYYY-MM-DD-bug-debugging-主题.md`。长期复核所需的脱敏输入与命令应可重建，不留下指向已删除临时文件的唯一复现入口；临时数据不自动入库，也不擅自修改忽略规则。

## 技能验收

修改本技能时，用 `references/evaluation-cases.md` 检查诊断准确性、确认前后的文件变化和验证诚实性。结构校验只证明技能可发现，不证明调试有效。