hunt

name	hunt
description	Bug 系统化排查。给定问题描述后先复现 → 定位 → 提假设 → 验证 → 再决定怎么修。任何 bug、回归、线上异常、"为什么不 work" 类问题开始前必须执行。

/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）

输出格式

## 现象
- 期望：...
- 实际：...
- 复现路径：...

## 最近变更
- 嫌疑 commit：abc1234（PR #N）
- 修改了：xxx

## 假设
### H1：...
- 为何成立：...
- 验证：跑 `xxx`
- 修复方向：...

### H2：...
（同上）

## 验证结果
- H1：证伪。理由：...
- H2：成立。证据：...

## 根因
（一两句话）

## 修复
- 改动：...
- 防回归：新增测试 `xxx.test.ts`，确保未来同类 bug 不再出现

## 验证
- 命令：`pnpm test`，全过 ✓
- 手测：原始复现路径不再触发

与其他 Skill 的关系

• 修复方案确定后用 /small-diff 控制改动范围
• 完成后用 /check 审查 diff 是否引入新问题
• 新发现的边界 case 用 /update-context 写入 gotchas