Immutable. This exact content is served forever at /api/v1/blob/b48791b559a7505b.
--- 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 の場合**: `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. `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つしかなく、親の直接調査だけでは不十分な場合に限り、追加の視点から調査する。独立した成果物や競合仮説の検証があり、調整コストを上回る場合だけsubagentを使い、それ以外は直接調査する。 **Step 3: 仮説-反証サイクル** - 各仮説に対して反証を行い、矛盾する証拠を探索する。独立した反証成果物が必要で調整コストを上回る場合だけ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)` を必要な数だけ起動して各アプローチの実現可能性を分析する。小規模な比較は直接行う。 2. `WebSearch` で類似問題の過去対応・公式推奨パターンを調査 **出力**: アプローチ列挙 + トレードオフ比較表 + 推奨と根拠 **詳細手順**: [phase3-comparison.md](references/phase3-comparison.md) を参照 **確認ゲート**: ユーザーが明示的にアプローチを選択 → Phase 4 へ ## Phase 4: TDD Implementation Plan（TDD実装計画の作成） **目的**: t-wada TDD理論に基づき、Red-Green-Refactorサイクルで実装計画を作成 **成果物の保持**: TDD実装計画は会話内のsession stateとして保持する。ファイル保存はユーザーが明示的に求めた場合のみ、保存先を確認して行う。 **TDDサイクル**: 修正全体を小さなサイクルに分解。各サイクル = 1つのテスト + 1つの修正 **詳細手順**: [phase4-tdd-plan.md](references/phase4-tdd-plan.md) を参照 **確認ゲート**: 計画レビュー → ユーザー承認。保存を求められた場合のみ、保存先を確認してファイルへ書き出して完了 ## GitHub コミュニケーションサポート メンテナーとのコミュニケーションが必要な場合: - **Issue/Discussion コメントドラフト**: ユーザーの代わりにドラフトを作成 - **質問の構造化**: 効果的な質問の構成を提案 - **投稿はユーザー判断**: `gh issue comment` や `gh pr comment` の実行はユーザーが決定 - **Discussion の読み取り**: `gh api graphql` で関連 Discussion を取得し分析に活用 ## エラーハンドリング | 状況 | 対応 | | ------ | ------ | | 無効なGitHub URL | 再入力を求める、またはテキスト入力にフォールバック | | プライベートリポジトリ | `gh auth login` のガイドを提示 | | テスト基盤なし | Phase 2 は再現ケースに集中、Phase 4 でテスト基盤セットアップを計画に含める | | コードベースが巨大 | Issue 内の手がかりに絞った Grep/Glob で対象を限定 | | 情報不足 | ユーザーに追加情報を求める、WebSearch で補完 |