diag

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。