| name | bug-fix |
| description | 【强制调用】用户说"fix/修改bug/修复/修一下/解决报错/不工作/报错/异常/debug/not working/error"等任何表达修复意图时必须调用。先诊断根因，评估难度，简单Bug直接修复，复杂Bug出多方案供选择。全程分支隔离，自测验证，最小化对其他模块影响。不适用于PPT、文档等非代码任务。 |
Bug 修复流程
核心原则
- 先诊断，再开药 — 使用
systematic-debugging 完成根因分析，根因未确认前禁止动手
- 最小影响 — 修改前评估对其他模块的影响；若引入新 bug，一并修复
- 分支隔离 — 使用
using-git-worktrees 创建 fix/issue-<编号>-<描述> 分支，禁止在主分支直接改
- 自测通过再交付 — 先模拟验证，再浏览器实测，全部通过才算完成
- 失败不钻死角 — 方案级失败换方案，代码级失败就地修，连续 3 次失败暂停并告知用户
- 全程记录 — 修复前读取项目
BUGFIX_LOG.md，完成后更新；同步写 memory 日志
- 中文交互
流程
一、收集信息
每次最多问 3 个问题：具体表现？预期行为？复现步骤？错误日志？必现还是偶发？安全类 Bug 追加追问数据泄露风险和外部触发可能。
二、根因分析
使用 systematic-debugging：读错误 → 定位代码 → 追踪数据流 → 检查近期变更 → 确认根因。
三、难度评估
🟢 简单 —— 跳过方案设计，直接修复： 拼写错误、字段未对齐、缺空值判断、逻辑符号反了、缺 await、配置遗漏、类型不匹配等，≤5 行、单文件改动。
🔴 复杂 —— 必须走方案设计： 其余所有情况。
四、方案设计（仅复杂 Bug）
产出 ≥2 个方案，每个方案评估对其他模块的影响：
方案 N：[名称]
- 思路：[一句话] | 修改范围：[文件清单]
- 优点：[2-3个] | 缺点/风险：[1-2个]
- 破坏性变更：[是/否] | 对其他模块的影响：[说明]
选最优并说明理由，难分优劣则交给用户选择。
五、修复计划 + 用户确认
## Bug 修复计划
Bug：[一句话] | 根因：[一句话] | 难度：[简单/复杂]
[复杂] 选定方案：[方案N] — 理由：[...]
修改文件：path/file — [改什么]
验证：1.模拟[...] 2.浏览器[...]
影响范围：[说明] | 预计行数：[...]
六、安全漏洞
涉及 XSS、SQL 注入、权限绕过、敏感数据泄露等：不公开讨论细节、优先评估影响面、commit 用 fix(security): <描述>、修复方案本身不能降低安全标准。
七、实施修复
- 按计划修改，不顺手重构无关代码
- 遵循项目编码规范，高内聚低耦合
- 修改时检查对其他模块的影响，发现会引入新 bug 则调整方案一并处理
- 需大面积架构调整 → 立即停止，向用户说明，由用户决策
八、验证测试
- 模拟验证（先做）： 构造输入 → 跟踪执行路径 → 验证输出 → 确认异常路径也处理
- 浏览器实测： 按复现步骤操作，确认 Bug 不复现，同时检查相关功能无回归
- 自动化测试（如有）： 运行测试套件
九、迭代修复
🟡 代码细节 → 直接修，重新验证，最多 3 轮
🔴 方案根本错误 → 优先调整方向；实在不行 git reset --hard（仅兜底），换备选方案
⛔ 所有方案失败 → 回到根因分析；连续 3 次失败暂停，告知用户
修复日志（双写）
项目日志：<项目根目录>/BUGFIX_LOG.md
修复前读取，完成后更新。格式：
## Bug 修复日志
### 2026-05-05：登录按钮点击无响应
- **根因：** 前端 onClick 绑定的事件名与后端接口路径不一致
- **难度：** 简单
- **方案：** 统一字段名为 `userLogin`
- **分支：** `fix/issue-1024-login-btn`
- **修改文件：** `src/api/auth.js`、`src/components/Login.vue`
Memory 日志
同步记录到 memory（project 类型），用于跨会话追踪迭代过程：
| 轮次 | 方案 | 结果 | 失败原因/新bug |
|---|
| 1 | A | ❌ | 影响模块X，导致新bug |
| 2 | B | ✅ | - |
红牌
| ⛔ 禁止 | ✅ 正确 |
|---|
| 没找到根因就改代码 | 回到根因分析 |
| 在主分支直接改 | 必须建分支 |
| 改完不验证 | 先模拟再浏览器 |
| 凑合能用的方案 | 选最优，选不出交给用户 |
| 顺手重构无关代码 | 只修 Bug |
| 大改不告知用户 | 第一时间说明 |
| 不检查对其他模块的影响 | 修改前评估，引入新bug一并修 |
