| name | diag |
| description | Disciplined bug-diagnosis loop. Reproduce → minimise → hypothesise → instrument → fix → regression-test. |
diag — 调 bug 的纪律循环
借鉴 mattpocock/skills 的 /diagnose. 当 verify 红了、有人报 bug、或者你"看起来好了但不放心"时用。
反模式:直接看代码"猜"原因然后改三个地方一起跑。不许。
6 步循环
1. Reproduce — 先稳定复现
- 写一个最小命令或测试让 bug 必然出现:
pnpm test src/auth/redirect.test.ts、curl -X POST …、UI 步骤序列。
- 不能复现 → 不算开始。先去找复现路径,不要修。
- 把复现命令写到
state/evidence/<task-id>/repro.md。
2. Minimise — 压到最小
- 从复现命令开始,一次删一样东西:去掉一个参数、一个文件、一个 mock、一个并发。
- 目标:找到"再删就不复现"的最小集合。这个最小集合就是 bug 的真实表面积。
3. Hypothesise — 写下 ≤3 个假设
H1: redirect 没 origin-check,外部 host 直接通过 → 应该 401 / 改写
H2: searchParams 在 SSR 拿到的是 undefined → fallback 错误
H3: middleware 顺序问题,redirect 在 auth 之前
按"如果错了,最先要修的"排序,不是按"我觉得最像的"。
4. Instrument — 看,不要猜
- 给每个假设设计一个观察点:日志、断言、单步调试、网络请求录制。
- 用
state/reference/ENV.md → Capture logs 的方法抓证据。
- 把证据存到
state/evidence/<task-id>/:日志、截图、trace、curl 输出。
- 看完证据先判定假设对错,再写代码。
5. Fix — 只改一处
- 改最小一处。不要"顺手"清理别的。
- 红 → 绿:先让最小复现命令变绿。
- 不要绕开 bug(比如 try/catch 吞掉),要修 bug。
6. Regression-test — 锁住,不再回归
- 把 step 1 的最小复现写成自动化测试留在仓库里。
- 这是 diag 唯一会留下的代码副产物(除了修复本身)。
- 没有 regression test 不算 done。
Output
每次 diag 结束,JOURNAL.md 追加:
**Did (diag):**
- Repro: `<cmd>`
- Min set: <最小集合>
- Hypotheses: H1✓ H2✗ H3✗ (证据见 state/evidence/<task-id>/)
- Fix: <one-line>
- Regression: <test path>
反模式速查
- 改了 3 个地方一起跑 → stop. revert. 一次改一个。
- "看起来好了" → 跑最小复现。
- "没法复现,但应该是 X" → 不要修。 把它写进 RISKS 等下次复现。
- 盲目加 try/catch → 你在隐藏 bug,不是修 bug。