Issue Analysis

---
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 の構造化情報を取得
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は独立、他の結果を知らない）:
   - 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つしかない場合、追加の視点から強制的に探索を起動

**Step 3: 仮説-反証サイクル**
- 各仮説に対して反証agentを起動し、矛盾する証拠を探索
- 反証結果に基づき仮説を採択/修正/棄却

**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)` で各アプローチの実現可能性を分析
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サイクル**: 修正全体を小さなサイクルに分解。各サイクル = 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 を取得し分析に活用

## エラーハンドリング

| 状況 | 対応 |
|------|------|
| 無効なGitHub URL | 再入力を求める、またはテキスト入力にフォールバック |
| プライベートリポジトリ | `gh auth login` のガイドを提示 |
| テスト基盤なし | Phase 2 は再現ケースに集中、Phase 4 でテスト基盤セットアップを計画に含める |
| コードベースが巨大 | Issue 内の手がかりに絞った Grep/Glob で対象を限定 |
| 情報不足 | ユーザーに追加情報を求める、WebSearch で補完 |