investigate-issue

GitHub の Issue を調査する

概要

調査では、ラベルを付けるだけでなく、実際のコードを確認して Issue の主張を検証し、根本原因を特定して、修正の方向性を提案します。出力するコメントは次のいずれかです。

• 確認済み — HEAD のコードで主張を検証し、修正の方向性を示しています。対応に着手できる状態です
• 却下 — 再現できない／すでに修正済み／前提が間違っている — Issue をクローズします
• 情報不足 — 重要な詳細が不足しています。status/needs-info を付けて終了します

調査 ≠ トリアージ：Issue ごとに 30 分から数時間かかり、5 分では終わりません。バックログ全体に実施しないでください。調査に値する Issue を選んでください。

使用するタイミング

• 本文の情報が少ない（タイトルと一文のみ） — 主張の裏付けが必要
• 本文で参照されているファイルや行番号が、変更やリファクタリングでずれている可能性がある
• 古い Issue（3 か月以上前） — HEAD でまだバグが存在するか確認する
• 修正用ブランチに割り当てる前 — まず根拠のある方針が必要
• ユーザーが「調査」「詳細調査」「検証」と求めている

使用しない場合：簡易トリアージで十分な場合（本文が詳しく、主張が明確で、必要なのがラベル付けのみの場合）。

手順

1. 本文を最後まで読む — すべての主張を確認します。

   • 参照されているファイルパス／行番号
   • 再現手順
   • 提案されている修正
   • 影響範囲（例：「10 個のエンドポイント」「すべての SSE ルート」）

2. 主張を検証する — 各ファイルと行番号を開きます。

   • 説明されているコードは HEAD に存在するか
   • ファイルは移動、改名、リファクタリングされているか
   • バグはまだ存在するか
   • 該当する場合は再現手順を実行する

3. 影響範囲を調べる — 本文に列挙されている範囲を鵜呑みにしないでください。

   • grep／Glob で同じアンチパターンがほかにもないか検索する
   • 疑わしい行の git blame を確認する — 最近の変更か、以前からあるものか
   • 関連するテストを確認する — この問題を検出できるか、テストは存在するか

4. 結果を決める：

   • 確認済み＋範囲を特定：検証済みの主張と具体的な修正方針をコメントする
   • 確認済みだが、本文の修正案が誤っている／不十分：その理由を説明し、代替案を提案する
   • 却下：理由を説明 → クローズする
   • 情報不足：具体的な質問をして、status/needs-info ラベルを付ける

5. 結果を反映する：

   • 調査後に優先度が変わった場合はラベルを更新する
   • 以下のテンプレートを使ってコメントする
   • 必要に応じて assignees を設定し、ドラフト PR へのリンクを追加する

コメントテンプレート

リポジトリの PR テンプレートのスタイルに合わせ、ひと目で内容を把握できるよう、見出しに絵文字を付けます。Issue 本文の言語に合わせてください。該当しないセクションは省略し、見出しだけを残さないでください。

## 🔬 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>

トリアージとの違い

	トリアージ	調査
本文を読む	はい	はい
コードを読む	いいえ	はい
ファイルや行番号を検証する	いいえ	はい
影響範囲を調べる	いいえ	はい
修正案を提案する	本文の内容を反映するのみ	独自に分析
所要時間／Issue	2～10 分	30 分～数時間
対象範囲	バックログ全体	1 件ずつ

トリアージ中にコードを読み始めたら、それは調査に踏み込んでいます。その Issue は最後まできちんと調査してください。中途半端な調査で終わらせないでください。

よくある間違い

• 確認せずに本文のファイル名や行番号を信頼する — コードは移動します。本文の情報は3か月前のものかもしれません。必ず確認してください。
• 本文で提案された修正で調査を終える — 本文に書かれているのは報告者の仮説であり、証明されたものではありません。根本原因に実際に対処できているか確認してください。
• 影響範囲の確認を省略する — 指摘された箇所だけを修正し、別の場所にある同一の4箇所を見落とします。
• バックログ全体を調査する — 規模が大きすぎて対応できません。効果の大きい課題を選んでください。
• 推測に基づく修正を提案する — HEADで確認できた内容のみを提案してください。確認できない場合は status/needs-info とラベルを付けて、そこで止めてください。
• 空のセクション見出し — 該当しないセクションは「N/A」と記入せず、省略してください。
• 「提案する方針」に判断事項を詰め込む — 実際のトレードオフや検証上の不足がある場合は、提案の中に埋もれさせず、「未解決の質問」に明示してください。担当者が推奨する方針から読み取るのではなく、質問をはっきり確認できるようにしてください。