18 added, 12 removed. Audit A to A.
---
name: issue-analysis
description: |
OSSのissue・バグレポート・機能提案を4フェーズで段階的に分析し、
TDDベースの実装計画を作成する。コード変更は行わず調査・分析・計画のみ。
- 独立並列調査→仮説-反証サイクル→証拠スコアリングにより、
+ 必要に応じた独立調査→仮説-反証サイクル→証拠スコアリングにより、
確証バイアス・アンカリング等の認知バイアスを排除した課題特定を行う。
ハルシネーション防止のためソース実在確認・WebSearchによる裏取りを実施。
推論過程・論拠・Next Actionを含む構造化レポートを出力する。
以下の場合に使用:
(1) OSSバグの原因特定と修正計画立案
(2) OSSへの機能追加の設計と計画
(3) GitHub Issue/Discussionの深掘り分析
(4) OSSコントリビューション前の学習と理解
(5) issueの真の原因を特定したい（表面的症状と根本原因を区別）
(6) 複数の可能性がある問題の切り分け
(7) 既存の分析が正しいか検証したい
disable-model-invocation: true
argument-hint: "[issue-url or description]"
---
# Issue Analyzer: OSS問題分析 → TDD実装計画
## 核心原則
- **コード変更禁止**: ソースコードの編集は一切行わない。読み取り専用操作のみ
- **仮説は複数、証拠で裁く**: 最初に見つけた原因を自動採用しない。必ず複数仮説を立て、コードベースの物的証拠で評価する
- **推論過程を隠さない**: 結論だけでなく、どう考えてその結論に至ったかを論拠付きで示す
- **ハルシネーション防止**: 引用するファイルパス・関数名・API仕様は必ず実在確認する。推論と事実を区別して明記する
- **ユーザー理解最優先**: AIがコードを書かず、ユーザーが手を動かして問題を理解する
- **シーケンシャル実行**: フェーズを飛ばす判断を自律的に行わない。必ず順番に進む
- **確認ゲート**: 各フェーズ完了後、ユーザーの明示的なOKなしに次へ進まない
## 入力処理
`$ARGUMENTS` の内容に応じて入力を処理する:
- 1. **GitHub URL の場合**: `Task` ツール（`subagent_type: "ctx:github"`）で Issue/PR/Discussion の構造化情報を取得
+ 1. **GitHub URL の場合**: `gh issue view` / `gh pr view --json`（`ctx:github` エージェントが登録されていればそれでもよい） で Issue/PR/Discussion の構造化情報を取得
2. **テキストの場合**: そのまま問題記述として使用
3. **引数なしの場合**: ユーザーに問題の説明を求める
## フェーズ進捗
このチェックリストをコピーし、各フェーズ完了時にチェックを更新して表示する:
```
Issue Analyzer Progress:
- [ ] Phase 1: Investigation（調査・問題理解）
- [ ] Phase 2: User Learning（ユーザーのハンズオン学習）
- [ ] Phase 3: Approach Comparison（修正方針の比較検討）
- [ ] Phase 4: TDD Plan（TDD実装計画の作成）
```
## 確認ゲートプロトコル
各フェーズ完了時に以下を実行:
1. フェーズの成果物を提示
2. 進捗チェックリストを更新表示
3. ユーザーに確認を求め、応答を待つ:
- **OK / 進めて** → 次のフェーズへ
- **質問** → 追加の説明を提供してから再度確認
- **戻って** → 前のフェーズの特定部分を再調査
- **中断** → 現時点までの成果物をコンソールに出力して終了
## Phase 1: Investigation（調査・問題理解・仮説検証）
**目的**: 問題の本質、影響範囲、依存関係を構造的に把握する。バイアスを排除した複数仮説の検証を経て、証拠に基づく課題特定を行う。
- **Step 1: 発散的調査（独立並列）**
- 1. `Task(ctx:github)` で Issue コンテキスト取得（URL入力時）
- 2. `Task(Explore)` を最大4並列で起動（各agentは独立、他の結果を知らない）:
+ **Step 1: 発散的調査**
+
+ 1. `gh issue view` で Issue コンテキスト取得（URL入力時）
+ 2. 小規模で直接調査が十分なら、subagentを起動せず親が調査する。独立した成果物や競合仮説があり、調整コストを上回る場合のみ、必要な数の `Task(Explore)` を並列起動する（固定数を必須にしない）。各agentは他の結果を知らずに調査する:
- Agent A: symptom-trace（症状からの逆追跡）
- Agent B: structural-analysis（構造的弱点分析、報告者の記述に依存しない）
- Agent C: historical-context（git log/blameからの変更履歴調査）
- Agent D: environmental-factors（条件付き: 外部依存がある場合のみ）
3. `WebSearch` / `WebFetch` で公式ドキュメント・類似Issueを収集
**Step 2: 仮説数の保証（N-of-1ルール）**
- - 仮説が1つしかない場合、追加の視点から強制的に探索を起動
+ - 仮説が1つしかなく、親の直接調査だけでは不十分な場合に限り、追加の視点から調査する。独立した成果物や競合仮説の検証があり、調整コストを上回る場合だけsubagentを使い、それ以外は直接調査する。
+
**Step 3: 仮説-反証サイクル**
- - 各仮説に対して反証agentを起動し、矛盾する証拠を探索
+
+ - 各仮説に対して反証を行い、矛盾する証拠を探索する。独立した反証成果物が必要で調整コストを上回る場合だけsubagentを使い、それ以外は直接検証する。
- 反証結果に基づき仮説を採択/修正/棄却
**Step 4: 証拠スコアリングとハルシネーション防止チェック**
+
- 証拠強度スコアリングで仮説をランキング
- 出力に含まれるファイルパス・関数名・API仕様を `Read` / `WebSearch` で実在確認
- [bias-checklist.md](references/bias-checklist.md) のセルフチェックを実行
**出力**: 構造化サマリー（問題定義、コード分析、テスト状況、**推論過程（仮説→検証→採択/棄却の経緯）**、論拠、Next Action、ドキュメント参照、未解明点）
**詳細手順**: [phase1-investigation.md](references/phase1-investigation.md) を参照
**確認ゲート**: サマリー提示 → ユーザーOK → Phase 2 へ
## Phase 2: User Learning（ユーザーのハンズオン学習）
**目的**: ユーザーが問題を自分の手で体験し、本質的に理解する
**核心**: AIはコードを書かない。場所と方針のみガイドし、ユーザーが実行する
**学習メソッド**（状況に応じて選択・組合せ）:
+
1. Print Debugging — 観察ポイント指定 → ユーザーが追加・実行・分析
2. 最小再現ケース — 段階的な再現構築をガイド
3. 失敗するユニットテスト — テスト方針提示 → ユーザーが書いて失敗を確認
**理解度チェック**: 原因の自分の言葉での説明、影響範囲の列挙、修正アイデア
**詳細手順**: [phase2-learning.md](references/phase2-learning.md) を参照
**確認ゲート**: 理解度チェック通過 + ユーザーOK → Phase 3 へ
## Phase 3: Approach Comparison（修正方針の比較検討）
**目的**: 複数の修正アプローチを比較し、最適な戦略を合意する
**サブエージェント戦略**:
- 1. `Task(Plan)` で各アプローチの実現可能性を分析
+
+ 1. 独立した比較成果物が必要で、調整コストを上回る場合だけ `Task(Plan)` を必要な数だけ起動して各アプローチの実現可能性を分析する。小規模な比較は直接行う。
2. `WebSearch` で類似問題の過去対応・公式推奨パターンを調査
**出力**: アプローチ列挙 + トレードオフ比較表 + 推奨と根拠
**詳細手順**: [phase3-comparison.md](references/phase3-comparison.md) を参照
**確認ゲート**: ユーザーが明示的にアプローチを選択 → Phase 4 へ
## Phase 4: TDD Implementation Plan（TDD実装計画の作成）
**目的**: t-wada TDD理論に基づき、Red-Green-Refactorサイクルで実装計画を作成
- **出力先**: `.claude/plans/issue-analyzer-{YYYY-MM-DD}-{short-description}.md`
+ **成果物の保持**: TDD実装計画は会話内のsession stateとして保持する。ファイル保存はユーザーが明示的に求めた場合のみ、保存先を確認して行う。
**TDDサイクル**: 修正全体を小さなサイクルに分解。各サイクル = 1つのテスト + 1つの修正
**詳細手順**: [phase4-tdd-plan.md](references/phase4-tdd-plan.md) を参照
- **確認ゲート**: 計画レビュー → ユーザー承認 → `.claude/plans/` に保存して完了
+ **確認ゲート**: 計画レビュー → ユーザー承認。保存を求められた場合のみ、保存先を確認してファイルへ書き出して完了
## GitHub コミュニケーションサポート
メンテナーとのコミュニケーションが必要な場合:
- **Issue/Discussion コメントドラフト**: ユーザーの代わりにドラフトを作成
- **質問の構造化**: 効果的な質問の構成を提案
- **投稿はユーザー判断**: `gh issue comment` や `gh pr comment` の実行はユーザーが決定
- - **Discussion の読み取り**: `Task(ctx:github)` で関連 Discussion を取得し分析に活用
+ - **Discussion の読み取り**: `gh api graphql` で関連 Discussion を取得し分析に活用
## エラーハンドリング
| 状況 | 対応 |
- |------|------|
+ | ------ | ------ |
| 無効なGitHub URL | 再入力を求める、またはテキスト入力にフォールバック |
| プライベートリポジトリ | `gh auth login` のガイドを提示 |
| テスト基盤なし | Phase 2 は再現ケースに集中、Phase 4 でテスト基盤セットアップを計画に含める |
| コードベースが巨大 | Issue 内の手がかりに絞った Grep/Glob で対象を限定 |
| 情報不足 | ユーザーに追加情報を求める、WebSearch で補完 |