hunt

# /hunt · Bug 系统化根因排查 ## 使用场景 - 报 bug：某个功能不 work / 行为不符合预期 - 测试失败：某个 test case 红了 - 回归：之前能跑的现在不能跑 - 线上异常：日志里出现错误堆栈 ## 目标 **找到根因再动手**——Agent 默认倾向于"看起来像 bug 就直接改"，结果往往是 patch 表面、留下根因不改，下次再以另一种形态复现。 ## 必须步骤 ### 1. 复现 - 先把 bug **稳定复现**——给出最小复现路径（命令 / 步骤 / 输入） - 如果暂时不能复现：说明"目前无法稳定复现"，**不允许**直接开始修 - 复现的同时把环境信息记下来：Node 版本、依赖版本、env 变量、相关日志 ### 2. 定位最近变更 - `git log --oneline -20` 看最近 commit - `git blame` 关注嫌疑代码的最近修改 - 找出**疑似引入 bug 的 commit / PR** ### 3. 提出假设 至少提 **2 个假设**。每个假设要回答： - 它如何解释观察到的现象？ - 怎么**验证**它（验证方法必须可执行：跑命令 / 加 log / 改测试）？ - 如果假设成立，**最小**修复方案是什么？ ### 4. 逐个验证假设 按"成本低的假设先验"的顺序。每验证一个： - 通过 → 进入修复阶段 - 证伪 → 记录"为什么不是"，转下一个 ### 5. 修复（仅在根因确认后） 修完后： - 跑一遍**原始复现路径**——bug 应消失 - 加 1 个测试用例**复现 + 修复证据**（防回归） - 在 `gotchas.md` 记一条"踩坑：xxx + 根因 yyy + 防回归方法 zzz" ## 禁止事项 - ❌ 未确认根因前**不允许**动代码 - ❌ 不允许用"反正这样改了就好了"作为根因 - ❌ 不允许删除 / 跳过让你不舒服的测试用例 - ❌ 不允许用 `--no-verify` 绕过 pre-commit 检查 - ❌ 不允许把"workaround"包装成"修复"（如必须 workaround，明确标注 `// TODO: workaround for X`） ## 输出格式 ```markdown ## 现象 - 期望：... - 实际：... - 复现路径：... ## 最近变更 - 嫌疑 commit：abc1234（PR #N） - 修改了：xxx ## 假设 ### H1：... - 为何成立：... - 验证：跑 `xxx` - 修复方向：... ### H2：... （同上） ## 验证结果 - H1：证伪。理由：... - H2：成立。证据：... ## 根因 （一两句话） ## 修复 - 改动：... - 防回归：新增测试 `xxx.test.ts`，确保未来同类 bug 不再出现 ## 验证 - 命令：`pnpm test`，全过 ✓ - 手测：原始复现路径不再触发 ``` ## 与其他 Skill 的关系 - 修复方案确定后用 [`/small-diff`](../small-diff/SKILL.md) 控制改动范围 - 完成后用 [`/check`](../check/SKILL.md) 审查 diff 是否引入新问题 - 新发现的边界 case 用 [`/update-context`](../update-context/SKILL.md) 写入 gotchas