range3/github-investigator

GitHub Investigator Skill

GitHub上である事柄（機能名、バグ、コンポーネント名など）についてどのような議論がされているかを gh CLI で調査し、要約レポートを生成する。

JSON処理のルール

gh の出力を加工する際は、必ず gh に組み込まれた --jq フラグを使う。| jq や | python3 -c ... などのパイプは原則として使わない。

理由: このスキルは gh * を中心とした permission allowlist で動作する前提のため、パイプを含むコマンドは permission prompt で止まる可能性がある。Bash(jq *) も frontmatter に入れているが、現時点では Claude Code のパイプ判定にバグが残っており確実に通る保証がない。--jq 一発で完結させれば gh * パターンにそのままマッチして安定動作する。

# 良い例: --jq フラグを使う
gh issue view 123 --repo OWNER/REPO --json comments --jq '.comments | length'
gh issue view 123 --repo OWNER/REPO --json title,state --jq '"\(.title) [\(.state)]"'

# 悪い例（やらないこと）
gh issue view 123 --repo OWNER/REPO --json comments | jq '.comments | length'
gh issue view 123 --repo OWNER/REPO --json comments | python3 -c "import json, sys; ..."

複雑な変換が必要な場合

--jq 一発では難しいと感じても、次の順で対処する。パイプには逃げない。

1. jq 式を頑張る: --jq には def（関数定義）、reduce、group_by、複数行式など jq のほぼ全機能が使える。複雑な変換も1つの式で書けることが多い（具体例は末尾の補足リファレンス参照）。
2. gh を複数回呼ぶ: 多段処理は、1段目の出力を見てから2段目の gh 呼び出しを組み立てる。中間結果は RESULT=$(gh ... --jq '...') でシェル変数に格納できる（gh * パターンに合致する形を保てる）。
3. 諦めて報告: それでも困難な場合は、生 JSON の概要だけ要約し、「より詳細な加工が必要」とユーザーに伝える。

注記: このルールは allowed-tools で gh と jq のみを許可していることに依存する。将来 allowlist を変更する場合はこのセクションも見直すこと。

前提条件

• gh CLI がインストール・認証済みであること
• 調査開始前に gh auth status で認証状態を確認し、未認証ならユーザーに案内する
• 対象リポジトリへのアクセス権があること（アクセス拒否された場合はその旨を報告し、パブリックリポジトリかどうかの確認を促す）

調査フロー

Step 0: 既存調査レポートの確認

依頼が継続調査を示唆する場合（「○○ の調査の続き」「このレポートを更新して」「再調査して」「最新の状況を反映して」など）、まず既存のレポート md を探す。既存レポートが見つかったら新規調査フロー（Step 1〜5）ではなく、継続調査モード（Step 6）に進む。

既存レポートの探し方

1. ユーザーがファイルを提示している場合: チャットに添付されている、@path/to/file.md のようにパスが明示されている、エディタで開いていることが言及されているなどの場合、そのファイルを読む。

2. トピック名で参照されている場合（例: 「ECConnector の調査の続き」「vLLM のメモリリーク調査どうなった？」）:

   • カレントディレクトリ周辺を探す:

     find . -maxdepth 3 -name "*.md" -type f 2>/dev/null
     

   • 候補ファイルの先頭数行（タイトル行とメタデータ）を確認し、トピック名が一致するものを特定:

     head -10 候補ファイル.md
     

   • 候補が複数あればユーザーに確認、ゼロなら新規調査として扱う

3. 継続を示唆する語がない場合: 通常の新規調査として Step 1 へ進む。

既存レポートから読み取る情報

見つかったレポートからは次を抽出する（詳細は Step 6 参照）:

• メタデータヘッダ（最終更新日、主リポジトリ、関連リポジトリ、検索キーワード）
• 本体に含まれる PR/Issue 番号一覧（追跡中の項目）
• 末尾「調査履歴」セクション（これまでの変遷）

Step 1: 調査対象の特定（新規調査の場合）

ユーザーの依頼文から以下を推測し、不明な点だけ確認する。毎回すべてを聞く必要はない。

• 検索キーワード: 調査したい事柄（例: ECConnector, authentication, memory leak）
• 対象リポジトリ: 下記の手順で特定する
• スコープ: Issue のみ / PR のみ / 両方（デフォルト: 両方）

リポジトリの特定

次の順で判断する。ほとんどのケースは 1〜3 のいずれかで解決する。

1. 明示されている場合: GitHub URL（https://github.com/owner/repo）、owner/repo 形式、org/repo 形式が依頼文に含まれていれば、そのまま使う。
2. 著名な OSS の名前が出ている場合: nodejs, vllm, rust, kubernetes, react など、名前からリポジトリ位置が一意に決まるものは自分の知識で解決する（例: vllm → vllm-project/vllm、rust → rust-lang/rust）。
3. マイナーな名前 / 知識にない場合: web 検索でリポジトリを特定してから調査に入る（例: 「LMCache を調べて」→ "LMCache GitHub" で検索 → LMCache/LMCache を特定 → 以降の gh コマンドはこのリポジトリを対象に実行）。
4. どうしても特定できない、または複数候補があって判断できない場合: ユーザーに確認する。ただしこれは稀なケースで、デフォルトは 1〜3 で進めること。

デフォルト動作

リポジトリと検索キーワードが揃ったら、スコープは Issue + PR の両方で始める。曖昧な場合のみユーザーに確認する。

Step 2: 全体像の把握（広く浅く）

いきなり個別の Issue に潜ると、重要な議論を見落としたり、特定の視点に偏ったりしやすい。最初に件数と傾向をつかんでから深掘りに移ることで、調査の網羅性と効率が上がる。

# Issue 検索
gh search issues "KEYWORD" --repo OWNER/REPO --limit 30 --sort updated --order desc

# PR 検索
gh search prs "KEYWORD" --repo OWNER/REPO --limit 30 --sort updated --order desc

レート制限への配慮: GitHub Search API は認証済みで 30 requests/min。1回の調査で複数キーワードを連続検索する場合や、Step 3 で多数の Issue/PR を詳細取得する場合は、sleep 2 等で間隔を空ける。エラーになってから対処するより事前に間隔を空けた方が結果的に速い。

結果が0件の場合: キーワードが具体的すぎる可能性がある。類義語や上位概念に広げて再検索する（例: ECConnector → connector, EC）。それでも0件なら、そのトピックについてリポジトリ上で議論が行われていない旨を報告する。

結果が多すぎる場合（50件超）: ラベルや期間で絞り込む。label:bug や created:>2024-01-01 などの修飾子を活用する（修飾子一覧は末尾の補足リファレンス参照）。

ここで一覧を眺め、以下のパターンを探す:

• 繰り返し登場する論点やキーワード
• 同じ人物が複数の Issue/PR に関与しているか
• open/closed の比率（未解決の割合が高いか）
• クローズされたがマージされなかった PR の有無: 「何が却下されたか」は設計判断の理解に直結する。見落としやすいので意識的にチェックする

Step 3: 深掘り（詳細取得）

Step 2 で関連性の高い Issue/PR を特定したら、詳細を取得する。議論の全容を把握するにはコメントまで読む必要があるが、すべてを読む必要はない。関連性の高いものから優先的に読み、通常は 5〜10件 程度の詳細取得で主要な論点はカバーできる。

# Issue 詳細
gh issue view NUMBER --repo OWNER/REPO \
  --json title,body,state,author,labels,comments,createdAt,closedAt,url

# PR 詳細（reviews にコードレビューの議論、files に影響範囲が含まれる）
gh pr view NUMBER --repo OWNER/REPO \
  --json title,body,state,author,labels,comments,reviews,files,commits,mergedAt,url

コメントが大量にある場合（30件超）: まずコメント数を確認（--json comments --jq '.comments | length'）し、すべてを処理しようとしない。最新の10件と、リアクションが多いコメントを優先して読む。古い議論は結論部分だけ拾えば十分なことが多い。

コンテキスト節約: 本文やコメントが非常に長い場合（例: 1万文字超）は --jq '.body[0:3000]' のように先頭を切り出して読み、必要なら追加で読む。JSON 全文をそのまま処理せず、必要な部分だけ取り出すこと（自分のコンテキストを圧迫しないため）。

PR の差分: 差分が大きい場合は、まず files で影響範囲の概要を把握してから、必要なファイルだけ diff を確認する。1000行を超える差分は全体を読む前に必ず files JSON で範囲を確認すること。

# 差分が必要な場合
gh pr diff NUMBER --repo OWNER/REPO

Step 4: 関連情報の補完（必要に応じて）

議論の経緯を正確に追うために、タイムラインや関連リソースが有用な場合がある。特に「なぜこの設計判断がなされたか」を追うときは複数のソースを組み合わせる。

タイムラインで経緯を追う

# Issue / PR のタイムライン（クロスリファレンスやラベル変更が含まれる）
gh api repos/OWNER/REPO/issues/NUMBER/timeline --paginate

Issue にひもづく PR を取得（GraphQL）

gh issue view --json には linked PRs が含まれない。確実に取得するにはタイムライン経由か GraphQL を使う。GraphQL のほうがノイズが少ない:

gh api graphql -f query='
  query($owner:String!, $repo:String!, $num:Int!) {
    repository(owner:$owner, name:$repo) {
      issue(number:$num) {
        title
        url
        timelineItems(itemTypes:[CROSS_REFERENCED_EVENT, CONNECTED_EVENT], first:20) {
          nodes {
            __typename
            ... on CrossReferencedEvent {
              willCloseTarget
              source { ... on PullRequest { number title state url } }
            }
            ... on ConnectedEvent {
              subject { ... on PullRequest { number title state url } }
            }
          }
        }
      }
    }
  }' -f owner=OWNER -f repo=REPO -F num=NUMBER

フィールドの読み方:

• __typename: イベント種別。CrossReferencedEvent は PR/Issue 本文での #123 参照、ConnectedEvent は GitHub UI の「Development」サイドバーから手動で link した場合に発生する
• willCloseTarget (CrossReferencedEvent のみ): true なら Closes #X / Fixes #X のように Issue を閉じる宣言付きの参照、false は単なる言及。レポートで「直接の解決関係」と「単なる言及」を区別したい時に使う
• -F num=NUMBER は Int として渡す必要がある（-f だと文字列扱いになり Int! の型チェックでエラーになる）。逆に owner / repo のような文字列引数は -f のほうが安全（リポジトリ名が数字に見える場合に -F だと誤って数値変換される）

コードの所在を把握

# 議論の前提となるコードの場所や使われ方を把握したいときに使う
gh search code "KEYWORD" --repo OWNER/REPO --limit 10

Issue/PR 以外の議論場所

リポジトリによっては設計議論が Issue/PR ではなく別の場所で行われている。次のいずれかが有効な場合がある。

• GitHub Discussions: 設計議論をここで行う OSS が増えている（Rust、Vite、Astro など）。

  gh api repos/OWNER/REPO/discussions
  

• コミットメッセージ: 「なぜこの実装になったか」の最終的な記録はコミット側にあることが多い。

  gh search commits "KEYWORD" --repo OWNER/REPO --limit 10
  

• リリースノート / CHANGELOG: 機能の登場・廃止の時系列把握に有用。

  gh release list --repo OWNER/REPO --limit 20
  gh release view TAG --repo OWNER/REPO
  

クロスリファレンスの追跡

コメントや本文中の #123 や他リポジトリへの参照は、関連性が高ければ追跡する。特に以下のパターンに注目:

• Closes #XX / Fixes #XX — 直接の解決関係
• Related to #XX — 関連する議論
• Depends on #XX / Blocked by #XX — 依存関係

ただし、すべての参照を追う必要はない。調査目的に直結するものだけを選ぶ。

Step 5: レポート作成

調査結果の規模に応じて適切なフォーマットを選ぶ。少数の Issue/PR しかない場合に大仰なレポートを作ると冗長になり、逆に多数の議論がある場合に簡潔すぎると情報が失われる。判断の目安は「ユーザーが結果を頭に入れられる量か」。

確度マーカー

各項目（特に「進行中の議論」）には、調査の深さを示すマーカーを付ける:

• [VERIFIED]: 該当 PR/Issue 本体（本文＋主要コメント）を実際に読んで確認した
• [INFERRED]: 複数の情報源（他 PR、コメント、議論）から推測して書いた
• [SHALLOW]: 表面的にしか調査していない。継続調査で深掘りする余地がある

これは「次回の継続調査で何を深掘りすべきか」の指針にもなる。すべての項目を [VERIFIED] にする必要はない。むしろ [SHALLOW] を残して優先度を伝えるほうが誠実。

規模ごとの出力形式

小規模（該当 3 件以下、またはユーザーが一覧を一目で把握できる量）: 散文で簡潔にまとめる。テンプレートを使わず、概要 + 関連リンクだけで十分。継続調査の枠組みも不要。

中規模（4〜10 件程度）: 下記テンプレートの章 1〜3 と章 5 のみ使う。章 4（タイムライン）と章 6（コントリビューター）は省略可。

大規模（10 件超 / 設計判断が複数絡む）: フルテンプレートを使う。

レポートテンプレート

# [トピック名] GitHub 議論調査レポート

**最終更新**: YYYY-MM-DD HH:MM JST
**対象トピック**: [自然文で1〜2行。何を調べているのか、読者が一読して理解できるレベル]
**主リポジトリ**: owner/repo
**関連リポジトリ**: [本トピックに関連する他リポジトリがあれば列挙。fork、plugin、依存ライブラリ、上流など]
**検索キーワード**: `keyword1`, `keyword2`, ...
**確度マーカー凡例**: [VERIFIED] 本体を読んで確認 / [INFERRED] 複数情報源から推測 / [SHALLOW] 表面的にしか調査していない

## 1. 概要

[2〜4 段落の散文。次の3点を含める:
 ・このトピックは何か（読者が一読して理解できるレベルで）
 ・なぜ存在するか / 何を解決するためのものか
 ・現在の主要な論点と方向性（決着済み vs 進行中の議論）
 リード段落は記事の見出しのように、興味を引き、要点を含む]

## 2. マージ済み PR / 確定した設計

[時系列または論理順で並べる]

### 2.1 [タイトル] (#番号) — YYYY-MM-DD マージ [VERIFIED]

**主導**: 名前 (handle) [複数なら列挙]

[本文: 何を変えたか、なぜそうしたか、どんな制約・トレードオフがあったか。
 具体的な数値（メモリ・性能・行数）、ファイルパス、命名変更の経緯など、
 後から「これはどこに実装されたのか」を辿るための錨を必ず埋め込む]

**参照**: 具体的なファイルパス、関連 RFC、コミットなど

### 2.2 ...

## 3. 進行中の議論

### 3.1 [論点タイトル] [INFERRED]

**関連 PR/Issue**: [#番号](url) (open) など

[本文: 論点の構造、誰が何を主張しているか、対立点はどこか、
 技術的な背景や制約があれば併記。引用は短く・必要なときだけ]

### 3.2 ...

## 4. タイムライン

\`\`\`mermaid
gantt
    title [トピック名] 開発タイムライン
    dateFormat YYYY-MM-DD
    section [カテゴリ1]
    [項目名] (#番号) :done, YYYY-MM-DD, YYYY-MM-DD
    section [カテゴリ2]
    [項目名] (#番号) :active, YYYY-MM-DD, YYYY-MM-DD
\`\`\`

[mermaid を使わない場合は箇条書きでも可。視覚的に時系列が見えることが目的]

## 5. 未解決の課題一覧

| 課題 | Issue/PR | 状態 | 備考 |
|------|---------|------|------|
| [課題名] | [#番号](url) | [方向性議論中 / 作業中 / 未着手 / RFC / stale] | [短いコメント] |

## 6. 主要コントリビューター

| 名前 | GitHub | 役割 |
|------|--------|------|
| [名前] | [handle] | [このトピックでの役割を1行で] |

---

# 調査履歴

[継続調査のたびに、ここに新しいエントリを **上から（新しい順に）** 追記する。
 既存のエントリは消さない。本セクションは Step 6 で更新される]

## YYYY-MM-DD の初回調査

**主要な発見**: [簡潔に、初回調査時点で何を発見したか・現状の要点]
**確認した主要 Issue/PR**: #XXX, #XXX, ...

出力先

• 新規調査: ファイル名は [topic-slug]-investigation.md を提案（例: ecconnector-vllm-investigation.md）。保存場所はカレントディレクトリをデフォルトとし、ユーザー指定があればそれに従う。
• 継続調査: 既存ファイルを同じパスに上書き保存。

クロスリポジトリ調査について

複数リポジトリにまたがるトピック（例: vLLM のプラグイン機構と上流の HuggingFace、fork で進行中の機能、依存ライブラリでの議論など）の場合:

• メタデータヘッダの 関連リポジトリ に列挙する
• 本文中で他リポジトリの Issue/PR に言及するときは owner/repo#番号 形式で書く（同じリポジトリなら #番号 のままで OK）
• 専用セクションを切るより、関連する文脈で自然に触れるほうが読みやすい（例: 「fake0fan の fork に NIXL ECConnector の作業が継続中」のように）

Step 6: 継続調査モード（既存レポートがある場合）

Step 0 で既存レポートを見つけた場合は、新規調査の Step 1〜5 を踏まず、ここに来る。新規調査と異なり、既存レポートを土台にして差分だけを効率的に把握する。

Step 6-1: 既存レポートから情報を抽出

レポートを読み込み、次を取得する:

• メタデータヘッダ: 最終更新日、主リポジトリ、関連リポジトリ、検索キーワード
• 本体の章 2・3・5 から PR/Issue 番号一覧: これが追跡中の項目
• 末尾「調査履歴」セクション: 過去にどんな変化があったか、何が決着し、何が動いていたか
• 確度マーカー: [SHALLOW] 印の項目は今回深掘りする候補

Step 6-2: 既知項目の状態チェック

抽出した PR/Issue 番号それぞれについて、現在の state と最終更新日を取得する:

# Issue
gh issue view NUMBER --repo OWNER/REPO --json number,title,state,updatedAt,closedAt

# PR
gh pr view NUMBER --repo OWNER/REPO --json number,title,state,updatedAt,mergedAt,closedAt

20件超なら sleep 2 を挟む。前回時点の state と比較して次のカテゴリに分類:

• 決着した: open → MERGED / CLOSED
• 動きあり: 状態は同じだが updatedAt が前回最終更新日より新しい
• 静かになった: 90日以上 updatedAt が動いていない（前回 active だったもの）
• 変化なし: 上記いずれにも該当しない

Step 6-3: 新規項目の探索

既存の検索キーワードで Step 2 と同様の検索を実行する。ただし updated:>YYYY-MM-DD を付けて前回最終更新日以降に絞る:

gh search issues "KEYWORD updated:>YYYY-MM-DD" --repo OWNER/REPO --limit 30
gh search prs    "KEYWORD updated:>YYYY-MM-DD" --repo OWNER/REPO --limit 30

ヒットしたうち、既存レポートにない番号が新規項目。中身を Step 3 と同様に深掘りする。

Step 6-4: レポートを更新

本体（章 1〜6）を完全に再生成する。前回の本体を上書きする形で、最新状態を反映したフル版を作る。

• 章 1（概要）: 状況が変わっていれば書き直す（例: 「議論中だった案が決着した」「新たな論点が登場した」）
• 章 2〜3: マージ済み・進行中の項目を最新状態で整理
• 章 4（タイムライン）: 新たなマージ・新規 Issue を追加
• 章 5（未解決の課題）: 決着した課題を削除、新規課題を追加
• 章 6: 新たな貢献者がいれば追加

確度マーカーは引き続き付ける。前回 [SHALLOW] だった項目で今回深掘りしたものは [VERIFIED] に昇格。

Step 6-5: 末尾「調査履歴」セクションに新エントリを追記

既存の履歴は消さず、新しいエントリを上（新しい順）に追加する。テンプレート:

## YYYY-MM-DD の更新

**前回更新**: YYYY-MM-DD

### 決着した項目
- **#XXXX (タイトル)**: [何が決着したか、いつマージ/クローズされたか]

### 動きがあった項目
- **#XXXX (タイトル)**: [どんな進展があったか、新たな議論があれば要点]

### 新規に登場した項目
- **#XXXX (タイトル)**: [概要、作成日、現在の状態]

### 静かになった項目
- **#XXXX (タイトル)**: [前回どうだったか、何日経過したか]

### 深掘りした [SHALLOW] 項目（あれば）
- **#XXXX**: [VERIFIED] に昇格。[何が分かったか]

すべてのサブセクションを毎回書く必要はない。該当がないサブセクションは省略してよい。

Step 6-6: ファイルを上書き保存

既存レポートと同じパスに保存する。バックアップは作らない（ファイル1つで完結する設計）。ユーザーが別の場所に保存したい場合のみ確認する。

エラー・トラブル対応

| 状況 | 対処 | |------|------| | gh auth status が未認証 | gh auth login の実行を案内する | | リポジトリへのアクセス拒否 | リポジトリの公開設定や権限を確認するよう案内する | | 検索結果が0件 | キーワードを広げて再検索（類義語・上位概念）。それでも0件なら報告 | | レート制限エラー (HTTP 403/429) | GitHub Search API は認証済みで 30 req/min が上限。403/429 が返ったら 30 秒以上待ってからリトライ。連続で発生する場合はユーザーに報告 | | コメントが100件超 | 全件読まない。最新10件 + リアクション上位を優先 | | diff が巨大（1000行超） | files で概要を先に把握し、関連ファイルだけ diff を見る |

補足

この調査では多くの情報を統合する必要があるため、結論を急がず、収集した情報を体系的に整理してからレポートを作成すること。

---

補足リファレンス

本文のステップでは主要なコマンドをインラインで示している。ここでは本文に書ききれなかった補足情報をまとめる。

検索修飾子

gh search issues と gh search prs で使える絞り込み修飾子。

| 修飾子 | 例 | 用途 | |--------|-----|------| | ラベル | gh search issues "KEYWORD label:bug" --repo OWNER/REPO | 特定ラベルに絞り込み | | 著者 | gh search issues "KEYWORD author:USERNAME" --repo OWNER/REPO | 特定ユーザーの投稿に絞り込み | | 状態 | gh search issues "KEYWORD state:open" --repo OWNER/REPO | open/closed で絞り込み | | 作成日 | gh search issues "KEYWORD created:>2024-01-01" --repo OWNER/REPO | 特定期間に絞り込み | | コメント数 | gh search issues "KEYWORD comments:>10" --repo OWNER/REPO | 議論が活発なものに絞り込み |

jq 加工パターン

--jq で使える典型的なフィルタ式。複雑な変換が必要な場合も、原則として --jq 一発で完結させる。

# コメント数だけ取得
gh issue view 123 --repo OWNER/REPO --json comments --jq '.comments | length'

# コメントの著者一覧（重複排除）
gh issue view 123 --repo OWNER/REPO --json comments --jq '[.comments[].author.login] | unique'

# PR で変更されたファイル名の一覧
gh pr view 456 --repo OWNER/REPO --json files --jq '.files[].path'

# 変更行数が多い順にファイルを表示
gh pr view 456 --repo OWNER/REPO --json files --jq '.files | sort_by(.additions + .deletions) | reverse | .[:5] | .[] | "\(.path) (+\(.additions)/-\(.deletions))"'

# 最新5件のコメント本文だけ取得
gh issue view 123 --repo OWNER/REPO --json comments --jq '.comments | .[-5:] | .[].body'

# 関数定義を含む複雑な変換（--jq でも def や reduce が使える）
gh pr view 456 --repo OWNER/REPO --json reviews --jq '
  def state_label: if . == "APPROVED" then "✓" elif . == "CHANGES_REQUESTED" then "✗" else "·" end;
  .reviews | group_by(.author.login) | map({user: .[0].author.login, last: .[-1].state | state_label})
'

GraphQL を使う場合

通常の調査は REST API（gh search / gh issue view 等）で十分だが、Issue にひもづく PR の取得や、複数オブジェクトの関連を一度に取得したいケースは gh api graphql を使う（具体例は Step 4 を参照）。