| name | plan:issue-analyzer |
| 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 の内容に応じて入力を処理する:
- GitHub URL の場合:
Task ツール（subagent_type: "ctx:github"）で Issue/PR/Discussion の構造化情報を取得
- テキストの場合: そのまま問題記述として使用
- 引数なしの場合: ユーザーに問題の説明を求める
フェーズ進捗
このチェックリストをコピーし、各フェーズ完了時にチェックを更新して表示する:
Issue Analyzer Progress:
- [ ] Phase 1: Investigation（調査・問題理解）
- [ ] Phase 2: User Learning（ユーザーのハンズオン学習）
- [ ] Phase 3: Approach Comparison（修正方針の比較検討）
- [ ] Phase 4: TDD Plan（TDD実装計画の作成）
確認ゲートプロトコル
各フェーズ完了時に以下を実行:
- フェーズの成果物を提示
- 進捗チェックリストを更新表示
- ユーザーに確認を求め、応答を待つ:
- OK / 進めて → 次のフェーズへ
- 質問 → 追加の説明を提供してから再度確認
- 戻って → 前のフェーズの特定部分を再調査
- 中断 → 現時点までの成果物をコンソールに出力して終了
Phase 1: Investigation（調査・問題理解・仮説検証）
目的: 問題の本質、影響範囲、依存関係を構造的に把握する。バイアスを排除した複数仮説の検証を経て、証拠に基づく課題特定を行う。
Step 1: 発散的調査（独立並列）
Task(ctx:github) で Issue コンテキスト取得（URL入力時）Task(Explore) を最大4並列で起動（各agentは独立、他の結果を知らない）:
- Agent A: symptom-trace（症状からの逆追跡）
- Agent B: structural-analysis（構造的弱点分析、報告者の記述に依存しない）
- Agent C: historical-context（git log/blameからの変更履歴調査）
- Agent D: environmental-factors（条件付き: 外部依存がある場合のみ）
WebSearch / WebFetch で公式ドキュメント・類似Issueを収集
Step 2: 仮説数の保証（N-of-1ルール）
- 仮説が1つしかない場合、追加の視点から強制的に探索を起動
Step 3: 仮説-反証サイクル
- 各仮説に対して反証agentを起動し、矛盾する証拠を探索
- 反証結果に基づき仮説を採択/修正/棄却
Step 4: 証拠スコアリングとハルシネーション防止チェック
- 証拠強度スコアリングで仮説をランキング
- 出力に含まれるファイルパス・関数名・API仕様を
Read / WebSearch で実在確認
- bias-checklist.md のセルフチェックを実行
出力: 構造化サマリー（問題定義、コード分析、テスト状況、推論過程（仮説→検証→採択/棄却の経緯）、論拠、Next Action、ドキュメント参照、未解明点）
詳細手順: phase1-investigation.md を参照
確認ゲート: サマリー提示 → ユーザーOK → Phase 2 へ
Phase 2: User Learning（ユーザーのハンズオン学習）
目的: ユーザーが問題を自分の手で体験し、本質的に理解する
核心: AIはコードを書かない。場所と方針のみガイドし、ユーザーが実行する
学習メソッド（状況に応じて選択・組合せ）:
- Print Debugging — 観察ポイント指定 → ユーザーが追加・実行・分析
- 最小再現ケース — 段階的な再現構築をガイド
- 失敗するユニットテスト — テスト方針提示 → ユーザーが書いて失敗を確認
理解度チェック: 原因の自分の言葉での説明、影響範囲の列挙、修正アイデア
詳細手順: phase2-learning.md を参照
確認ゲート: 理解度チェック通過 + ユーザーOK → Phase 3 へ
Phase 3: Approach Comparison（修正方針の比較検討）
目的: 複数の修正アプローチを比較し、最適な戦略を合意する
サブエージェント戦略:
Task(Plan) で各アプローチの実現可能性を分析WebSearch で類似問題の過去対応・公式推奨パターンを調査
出力: アプローチ列挙 + トレードオフ比較表 + 推奨と根拠
詳細手順: 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 を参照
確認ゲート: 計画レビュー → ユーザー承認 → .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 で補完 |
