investigate-issue

调查 GitHub 问题

概述

调查不止是添加标签，还要根据实际代码核实问题中的说法、确认根本原因，并提出修复方向。输出是一条评论，内容应为以下之一：

• 确认 — 已根据 HEAD 核实问题中的说法，已说明修复方向，可以着手处理
• 驳回 — 无法复现／已修复／前提有误——关闭问题
• 需要更多信息 — 缺少关键信息；添加 status/needs-info 标签并停止

调查 ≠ 分类：每个问题需要 30 分钟到数小时，而不是 5 分钟。不要对整个待处理列表执行调查，只挑选值得调查的问题。

适用情形

• 正文内容稀少（标题 + 一句话）——需要证实其中的说法
• 正文引用了文件:行号，但相关代码可能已移动／重构
• 问题发布已久（超过 3 个月）——核实该错误在 HEAD 中是否仍然存在
• 准备将问题分配到修复分支——需要先确定合理的修复方向
• 用户提出“调查”“深入分析”或“核实”

以下情形不适用：简单分类就足够（正文内容详尽、说法明确，只需要添加标签）。

流程

1. 完整阅读正文 — 记录每一项说法：

   • 引用的文件路径／行号
   • 复现步骤
   • 建议的修复方案
   • 受影响范围（例如“10 个端点”“所有 SSE 路由”）

2. 核实说法 — 打开每个文件:行号：

   • HEAD 中是否存在所描述的代码？
   • 文件是否已移动、重命名或重构？
   • 错误是否仍然存在？
   • 如适用，执行复现步骤。

3. 探查影响范围 — 不要轻信正文列举的范围：

   • 使用 grep / Glob 在其他位置查找相同的反模式
   • 对可疑行运行 git blame — 是近期更改还是早已有之？
   • 检查相关测试——这些测试能发现此问题吗？是否存在相关测试？

4. 决定结果：

   • 已确认且范围明确：发表评论，写明已核实的说法和具体修复方向
   • 已确认，但正文中的修复方案有误／不完整：说明原因并提出替代方案
   • 驳回：说明原因 → 关闭问题
   • 需要更多信息：提出具体问题，添加 status/needs-info 标签

5. 执行后续操作：

   • 如果调查后优先级发生变化，更新标签
   • 使用下方模板发表评论
   • 可选：设置 assignees，链接到草稿 PR

评论模板

遵循仓库的 PR 模板风格——使用带表情符号的分节标题，方便快速浏览。使用与问题正文相同的语言。跳过不适用的部分（不要留下空标题）。

## 🔬 Investigation YYYY-MM-DD

**Verdict**: confirmed · dismissed · needs-info
**Adjusted priority**: <only if triage call changed after investigation>

### 📊 At a Glance

<diagram (mermaid or ascii) + 1-line caption — show the verified mechanism, not a text summary>

Use a diagram when investigating:

- Security: `sequenceDiagram` of attack chain confirming where the actual exploit happens
- Race condition: `sequenceDiagram` of concurrent timeline
- Refactor: `flowchart` of current vs proposed module shape
- Cluster of broken-together bugs: `flowchart LR` of dependency

Skip the section if the verdict line + Verified bullets already make the picture obvious.

### ✅ Verified

- <file:line still valid as of `<sha>` / matches body's description>
- <reproduction confirmed via `<command / scenario>`>
- <blast radius: N additional sites at `<paths>`>

### ❌ Body inaccuracies

<only if applicable — e.g. "body says fix is at A, actual root cause is B because...">

### 🛠 Proposed Direction

<2-4 lines — concrete fix path. File paths + shape of change. Not full code.>

### ❓ Open Questions

<only when investigation surfaces decisions / tradeoffs / verification gaps that the issue owner needs to resolve before fix can land>

Format each as: `**<question>** — <type>. <your lean if any>`
Types: `decision needed` · `tradeoff` · `verification gap`

Skip the section when there's nothing genuinely undecided. Forced "questions" become noise.

### 🔗 Related

<cross-links if relevant>

与分类的区别

	分类	调查
阅读正文	是	是
阅读代码	否	是
核实文件:行号	否	是
探查影响范围	否	是
提出修复方案	仅复述正文	自行分析
每个问题耗时	2–10 分钟	30 分钟到数小时
范围	整个待处理列表	每次一个问题

如果在分类过程中开始阅读代码，就已经进入调查阶段了——请把这个问题完整调查完。不要只调查一半。

常见错误

• 不经核查就相信正文中的文件:行号 — 代码会变动。正文中的信息可能已经过时 3 个月。务必核实。
• 止步于正文中建议的修复方案 — 正文只是报告者的假设，并未得到证实。请确认该方案确实解决了根本原因。
• 忽略影响范围 — 只修复提到的一个位置，却漏掉其他地方 4 处相同的位置。
• 调查整个积压问题列表 — 这种做法无法扩展。优先处理影响力大的问题。
• 提出推测性的修复方案 — 只提出你已在 HEAD 验证过的方案。如果无法验证，请标记 status/needs-info 并停止。
• 留下空的章节标题 — 不适用的章节应省略，而不是填上“无”。
• 把决策塞进 Proposed Direction — 如果存在实际取舍或验证缺口，应在 Open Questions 下明确提出，而不是埋在提案中。负责人应该能直接看到问题，而不必从建议方案中费力找出。