/research — 焦点を絞った調査

使用する場面

• 依存関係が新しいバージョンを持つかどうか、または廃止されているかどうかを評価する
• 特定の技術的な問題に対するコミュニティのベストプラクティスを見つける
• API またはライブラリの公式ドキュメントを読む
• 同様の問題を解決する他のプロジェクトの方法を調査する
• コードベースで使用されているパターンに既知の問題があるかどうかを確認する
• 決定を下す前に外部情報が必要な場合

使用しない場面: 質問に 3 個以上の独立した小問題がある場合(/research-fleet を並列スカウト用に使用); 調査結果に直ちに対応する必要がある場合(/marshal を使用。内部で /research を呼び出します)。

プロトコル

ステップ 1: 定式化

研究質問を 2～4 個の具体的な検索クエリに変換します:

• 公式ドキュメント クエリ (例: "express.js middleware error handling docs")
• コミュニティ/GitHub クエリ (例: "express error middleware best practices site:github.com")
• 技術ブログ/比較クエリ (例: "express vs fastify error handling 2025")
• バージョン固有の場合はリリースノート クエリ (例: "express 5.x changelog breaking changes")

検索前に質問を 1 文で明確に述べます。

ステップ 2: 検索

検索を実行して実際のコンテンツを読みます (スニペットだけではなく):

• 発見には WebSearch を、実際のページの読み込みには WebFetch を使用
• ソースの信頼性を評価: 公式ドキュメント > スター数の多い GitHub リポジトリ > 最近のブログ記事 > フォーラムの回答
• 3～6 個の信頼できるソースで停止 (網羅的ではなく、焦点を絞った検索)
• ソースが別のソースと矛盾する場合は、その不一致に注意してください

ステップ 3: 抽出

各調査結果について、以下を記録します:

• 内容: 発見された具体的な事実、推奨事項、またはパターン
• ソース: URL またはリファレンス
• 関連性: これが元の質問にどのように適用されるか (1 文)
• 信頼度: 高 (公式ドキュメント、検証済み)、中 (コミュニティのコンセンサス)、低 (単一ソース、意見)
• アクション: コードベースがこの情報をどのように使用すべきか (または「情報提供のみ」)

ステップ 4: 作成

調査結果を .planning/research/{topic-slug}.md に書き込みます:

# Research: {Topic}

> Question: {元の質問}
> Date: {ISO date}
> Confidence: {全体: high/medium/low}

## Findings

### 1. {調査結果のタイトル}
**What:** {説明}
**Source:** {URL}
**Confidence:** {high/medium/low}
**Action:** {推奨事項または「情報提供のみ」}

### 2. {調査結果のタイトル}
...

## Summary
{2～3 文: 学んだこと、推奨事項は何か}

## Open Questions
{解決できなかったこと — 人間の判断またはより深い調査が必要}

ステップ 5: 返却

概要と推奨事項を呼び出し元 (ユーザー、Marshal、または Archon) に返します。 調査ドキュメントは将来の参照のために保持されます。

/research が行わないこと

• アーキテクチャの決定を下す (それは呼び出し元の仕事です)
• パッケージをインストールしたりコードを修正したりする
• 網羅的に検索する (2～4 個のクエリ、3～6 個のソース、完了)
• 主観的な意見を事実として評価する
• 証拠なしに推奨する

境界事例

• Web アクセスが利用できない: ローカル専用の調査にフォールバックします。コードベースを検索し、ドキュメント ファイルを読み、package.json をチェックし、ローカル ソースから調査結果を生成します。研究ドキュメントの信頼度レベルにこの制限を記載してください。
• 検索が関連する結果を返さない: クエリを拡張 (バージョン固有の用語を削除、同義語を試す)、別の角度をもう 1 つ試します。それでも空の場合は、不確実性を明示的に報告します: 「強力な証拠が見つかりません。人間による確認をお勧めします。」
• .planning/research/ が存在しない: 調査結果ドキュメントを書き込む前に作成します。出力ディレクトリがない場合はエラーが発生してはいけません。
• 矛盾するソース: 1 つを黙って選択するのではなく、調査結果で矛盾を明確に表示します。両方の見方がドキュメントに属しています。
• 質問が 3～6 個のソースには広すぎる: 最も重要な単一の小問題に絞り込み、よく答え、スコープから外されたものを記載します。複数角度の質問には /research-fleet を提案します。

コンテキスト ゲート

可逆性: グリーン — .planning/research/ に 1 つのファイルを書き込みます; 削除して元に戻します。 コスト: コスト 0 のアクション — Web 検索と 1 つのファイル書き込み; エージェントは生成されず、確認は不要です。 信頼: ゲートなし — 読み取り専用調査、すべての信頼レベルで安全です。

品質ゲート

• すべての調査結果にはソース URL が必要です
• 信頼度レベルは正当化される必要があります (推測ではなく)
• 概要は元の質問に答えるか、答えられない理由を述べる必要があります
• 調査結果を返す前に研究ドキュメントを書き込む必要があります

終了プロトコル

調査結果の概要を出力してから、以下を実行します:

---HANDOFF---
- Research: {topic}
- Findings: {count} sources analyzed
- Recommendation: {one-line summary}
- Document: .planning/research/{slug}.md
- Reversibility: green — one file written to .planning/research/; delete to undo
---