xdev-bugfix

/xdev-bugfix — Bug 修复流程

Bug 描述： 用户消息（手势之外的原文）

本流程是 /xdev-full-dev 阶段 3–4 的 bugfix 特化。硬规则 1–5 全部生效（见 /xdev-full-dev）， 本文件只写 bugfix 不同于 full-dev 的部分：如何定位根因、何时升级、以及阶段 3–4 里 "计划 / Intent Contract / 任务" 在没有设计文档时的替代物。

分级（决定路径，判定后告知用户即继续）

级别	特征	路径
S1 快修	单文件、根因一眼可见（配置 / 文案 / 明显笔误）	回归测试 → 修 → 聚焦测试 → 直接推分支，不开 PR
S2 标准	单模块逻辑错误、可稳定复现	内联定位 → TDD → 全量测试 → 交付
S3 深度	跨模块 / 间歇性 / 竞态 / 数据损坏	blame/bisect → 卡住则 fresh 调查 → TDD → 全量测试 → 交付

升级规则：S1 修着发现牵涉 >1 文件 → S2；S2 两次取证或一次假设验证失败 → S3；任何级别修后全量测试失败 → 回到调查，不降级。修复涉及 >5 文件 → 🔴 停下请用户确认方向。 若报错发生在研究/实验语境（复现论文、跑实验矩阵），修复完成后回到 /xdev-research 继续研究流程——bugfix 只负责修通，研究结论归 research 产出。

分支：在 main/master 上则先 git switch -c xdev-bugfix-<slug>（或 worktree；注意 worktree 不带 .env* 与构建产物，首次跑测试前按需拷贝 / 重装）。

阶段 1：定位根因

先用 git 证据，再提假设（比猜快 3–5 倍，且客观）：

git log --oneline -20 -- <affected-files>
git blame -L <start>,<end> <file>
git bisect start && git bisect bad HEAD && git bisect good <last-known-good>   # 知道上次正常版本时

blame/bisect 已定位到引入 commit 且 diff 一目了然 → 直接进阶段 2。

卡住时（S3）派发 fresh 调查 subagent，把 blame/bisect 结果作为输入：

你是根因调查员，只读代码 / 日志 / 历史 diff，不修改任何文件。输入：bug 描述、复现步骤、
blame/bisect 定位结果。产出：根因假设（按置信度排序）、每条的 file:line 证据、最小验证方法、
本次修复的预期影响范围（文件 / 模块）。

假设连续 2 次验证失败，第 3 次必须换方向（重读被忽略的线索：stack trace / 日志 / 相邻模块；组合两次"部分成立"的交集；考虑竞态 / 环境 / 数据损坏），仍失败 → 🔴 暂停请用户介入。换向由主线程判断，不写进调查 prompt。

阶段 2：TDD 修复（= full-dev 阶段 3，单任务）

对 full-dev 阶段 3 术语的替代：任务 = 这一个修复；Intent Contract = 根因报告中的 "预期影响范围"（无报告时 = 引入 bug 的 commit diff 涉及的文件）。

1. 先写复现 bug 的回归测试，跑一次确认真的失败（S1 纯配置 / 文案无法写测试时标 [manual-verify] 并写明手动步骤）
2. 反向确认（硬规则 2 在 bugfix 下的形态，不可跳过）：修复完成后，把修复退回原状 （git stash / git checkout -- <file> / 临时还原那几行），重跑第 1 步的同一条命令—— 它必须重新失败。仍然通过 → 这条回归测试没有测到你修的东西（假绿），回到第 1 步重写。 退不回去时（多文件交织修复）写明理由，并在报告中标 未反向确认，不得默认它已确认。
3. 同类扫描：对刚修好的那个模式做一次全仓 rg，报告"同款 N 处、本次修 M 处"。 只修实例不清类 = 同一个 bug 换个文件继续活着。实盘：某次修复在 core/tank.ts 抓出并修好了 "测试断言的是程序不引用的死模块"，同类的 core/powerup.ts 活到了交付，导致两条验收标准的 证据链整条建在死模块上。扫出的其余同款：一处一句理由，或开新 issue，不要顺手全改（越范围）。
4. 最小修复：只改根因，不顺手重构
5. 跑回归测试到通过；再跑项目约定的全量测试 + lint/build
6. commit：fix: <root cause>，正文写 Root cause / Fix 两行