investigate-issue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Investigating a GitHub Issue

GitHub问题调查指南

Overview

概述

Investigation goes beyond labels to verify the issue's claims against actual code, confirm root cause, and propose a fix direction. Output is a comment that either:

Confirms — claims verified against HEAD, fix direction stated, ready for pickup
Dismisses — not reproducible / already fixed / wrong premise — close it
Needs-info — missing critical detail; tag
```
status/needs-info
```
and stop

Investigation ≠ triage: 30 min – hours per issue, not 5 min. Don't run it on the whole backlog. Pick issues that earn it.

调查不仅仅是添加标签，而是要对照实际代码验证问题描述的真实性、确认根本原因，并提出修复方向。输出内容为一条评论，评论需符合以下三种结果之一：

确认 —— 基于HEAD版本验证问题描述属实，明确修复方向，等待开发人员接手
驳回 —— 问题无法复现/已修复/前提错误 —— 关闭该问题
需要补充信息 —— 缺少关键细节；添加
```
status/needs-info
```
标签并终止调查

调查≠分类筛选：每个问题需耗时30分钟至数小时，而非5分钟。不要对所有积压问题都执行调查，只选择值得深入分析的问题。

When to Use

使用场景

Body is sparse (title + one-liner) — claims need substantiating
Body references file:line that may have moved / been refactored since
An old issue (>3 months) — verify the bug still exists at HEAD
About to assign to a fix branch — defensible direction needed first
The user says "investigate", "deep-dive", or "verify"

Don't use when light triage is enough (body is thorough, claims unambiguous, only need labels).

问题描述内容简略（仅标题+一句话）—— 需要验证描述的真实性
问题描述中引用了文件:行号，但可能已被移动/重构
旧问题（超过3个月）—— 验证该缺陷在HEAD版本中是否仍然存在
即将分配至修复分支前—— 需要先确定合理的修复方向
用户明确要求“调查”“深入分析”或“验证”

请勿使用：当简单分类筛选即可处理时（问题描述详尽、内容明确，仅需添加标签）。

Process

流程

Read the body completely — note every claim:
- File paths / line numbers referenced
- Reproduction steps
- Suggested fix
- Affected scope (e.g. "10 endpoints", "all SSE routes")
Verify the claims — open each file:line:
- Does the described code exist at HEAD?
- Has the file moved, been renamed, or been refactored?
- Is the bug still present?
- Run repro steps if applicable.
Probe blast radius — don't trust the body's enumeration:
- ```
grep
```
  / Glob for the same anti-pattern elsewhere
- ```
git blame
```
  on suspect lines — recent change? old?
- Check related tests — would they catch this? do they exist?
Decide outcome:
- Confirmed + scoped: post comment with verified claims + concrete fix direction
- Confirmed but body's fix is wrong / incomplete: explain why, propose alternative
- Dismissed: explain why → close
- Needs-info: ask specific questions, label
```
status/needs-info
```
Apply outcome:
- Update labels if priority changes after investigation
- Post comment via template below
- Optionally
```
assignees
```
  , link to draft PR

完整阅读问题描述 —— 记录所有描述内容：
- 引用的文件路径/行号
- 复现步骤
- 建议的修复方案
- 影响范围（例如：“10个端点”、“所有SSE路由”）
验证描述内容 —— 打开每个引用的文件:行号：
- 描述中的代码在HEAD版本中是否存在？
- 文件是否已移动、重命名或重构？
- 缺陷是否仍然存在？
- 如有必要，执行复现步骤。
排查影响范围 —— 不要完全信任问题描述中的列举：
- 使用
```
grep
```
  /Glob命令查找代码库中是否存在相同的不良模式
- 对可疑代码行执行
```
git blame
```
  —— 是近期修改的？还是旧代码？
- 检查相关测试用例—— 测试是否能发现该问题？测试用例是否存在？
确定处理结果：
- 已确认且明确范围：发布评论，包含已验证的内容+具体修复方向
- 已确认但描述中的修复方案错误/不完整：解释原因，提出替代方案
- 驳回：解释原因 → 关闭问题
- 需要补充信息：提出具体问题，添加
```
status/needs-info
```
  标签
执行处理结果：
- 若调查后优先级有变化，更新标签
- 使用下方模板发布评论
- 可选：分配处理人员，关联草稿PR

Comment Template

评论模板

Match repo's PR template style — emoji-headed sections for at-a-glance scanning. Match issue body's language. Skip sections that don't apply (don't leave empty headers).

markdown

undefined

匹配仓库的PR模板风格—— 使用带emoji的标题以便快速浏览。使用与问题描述一致的语言。跳过不适用的章节（不要保留空标题）。

markdown

undefined

🔬 Investigation YYYY-MM-DD

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

📊 At a Glance

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.

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>
```
>

<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

🛠 Proposed Direction

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

❓ Open Questions

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.

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> ```

Difference from Triage

与分类筛选的区别

	Triage	Investigation
Reads body	yes	yes
Reads code	no	yes
Verifies file:line	no	yes
Probes blast radius	no	yes
Proposes fix	only echoes body	own analysis
Time / issue	2–10 min	30 min – hours
Scope	whole backlog	one issue at a time

If you start reading code during a triage, you've crossed into investigation — finish that one issue properly. Don't half-investigate.

	Triage（分类筛选）	Investigation（调查）
阅读问题描述	是	是
阅读代码	否	是
验证文件:行号	否	是
排查影响范围	否	是
提出修复方案	仅复述描述内容	自主分析得出
每个问题耗时	2–10分钟	30分钟至数小时
适用范围	所有积压问题	每次仅处理一个问题

如果在分类筛选过程中开始阅读代码，那么你已经进入了调查阶段——请完整处理该问题，不要半途而废。

Common Mistakes

常见误区

Trusting body's file:line without checking — code moves. The body might be 3 months stale. Always verify.
Stopping at the body's suggested fix — body is the reporter's hypothesis, not proven. Verify it actually addresses root cause.
Skipping blast radius — fix the one site mentioned, miss 4 identical sites elsewhere.
Investigating the whole backlog — doesn't scale. Pick high-leverage issues.
Proposing speculative fixes — only propose what you've verified at HEAD. If you can't verify, label
```
status/needs-info
```
and stop.
Empty section headers — sections that don't apply should be omitted, not filled with "N/A".
Stuffing decisions into Proposed Direction — if there's a real tradeoff or verification gap, surface it under Open Questions instead of burying it in the proposal. The owner should see the question explicitly, not have to mine it out of the recommended path.

未验证就信任描述中的文件:行号 —— 代码会变动。问题描述可能是3个月前的旧内容。务必验证。
停留在描述建议的修复方案上 —— 描述是报告者的假设，而非已证实的结论。需验证该方案是否真能解决根本原因。
跳过影响范围排查 —— 修复了描述中提到的一处问题，却遗漏了代码库中另外4处相同的问题。
对所有积压问题执行调查 —— 这种方式无法规模化。只选择高价值的问题。
提出推测性的修复方案 —— 仅提出基于HEAD版本已验证的方案。如果无法验证，添加
```
status/needs-info
```
标签并终止调查。
保留空章节标题 —— 不适用的章节应直接省略，不要填充“N/A”。
将决策内容混入修复方向 —— 如果存在实际的权衡或验证缺口，请在“待解决问题”部分明确列出，而非隐藏在修复建议中。问题负责人需要明确看到这些问题，而不是从建议方案中自行挖掘。