research

name	research
description	研究テーマ・問いを 調査 → 集約 → 思考 → 仮説 の流れで掘り下げる研究ワークフロー。Web とローカルの両方を調べ、事実を集約し、構造分析してから検証可能な仮説を立てる。「研究して」「調べて考えて仮説立てて」「〜について深く掘り下げて」「〜って本当なのか検証したい」「〜の原因を調べて仮説を立てて」といった要望に対応する。コードの実装・バグ修正・デバッグが目的のとき（それは /pir2 や /debug）ではなく、テーマそのものの探究・分析・仮説形成が目的のときに使う。ユーザーが /research と入力したら必ずこのスキルを使う。
argument-hint	["研究テーマ・問い"]

Research — 調査 → 思考 → 仮説

研究ワークフローを実行します。このスキル本体（= メイン Codex, Opus）がオーケストレーターとなり、explorer（調査）→ 集約（オーケストレーター自身）→ thinker（思考）→ hypothesizer（仮説）を Agent ツールで順に起動します。集約フェーズはサブエージェントに委譲せず、オーケストレーター自身が探索結果を統合します。サブエージェントも Agent ツールでネスト起動できますが、本ワークフローでは制御フロー（起動・ゲート管理・成果物集約・ユーザー確認）をスキル本体に集約する設計とし、サブからのネスト起動は read-only の探索（explorer）に限ります。

テーマ: $ARGUMENTS

各フェーズのモデル割当:

フェーズ	担当	モデル
調査	explorer（最大3体並列）	sonnet
集約	オーケレーター（スキル本体）	opus（= メインセッション）
思考	thinker	fable
仮説	hypothesizer	opus

---

ステップ 0: RUN_DIR の確定

以下の Bash コマンドで PROJECT_ROOT / RUN_DIR を確定し、以降のすべてのステップで使用してください:

PROJECT_ROOT="$(pwd)"
run_ts="$(date +%Y%m%d-%H%M%S)"
run_feature="$(printf '%s' "$ARGUMENTS" | tr -c 'a-zA-Z0-9' '-' | sed -E 's/-+/-/g; s/^-//; s/-$//' | cut -c1-40)"
[ -z "$run_feature" ] && run_feature="research"
# RUN_DIR の基底パス SSOT は ~/.agents/skills/pir2/references/run-dir-base.md（PROJECT_ROOT 基底、sanitize 不要）
RUN_DIR="${PROJECT_ROOT}/.ai-pir-runs/${run_ts}-${run_feature}"
mkdir -p "$RUN_DIR"
# 中間ファイルを git 追跡から外す（git リポジトリのときのみ）
if git -C "$PROJECT_ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
  grep -qxF '/.ai-pir-runs/' "${PROJECT_ROOT}/.gitignore" 2>/dev/null || echo '/.ai-pir-runs/' >> "${PROJECT_ROOT}/.gitignore"
fi
echo "PROJECT_ROOT=$PROJECT_ROOT"
echo "RUN_DIR=$RUN_DIR"

/research は探究ワークフローであり、handoff 連携・プロジェクトメモリ追記は行いません（HANDOFF_PATH / PROJECT_MEMORY_DIR は不要）。

以降の各サブエージェントへのプロンプトには必ず RUN_DIR=[パス] を含めてください。

---

ステップ 1: 調査フェーズ（explorer, Sonnet）

研究テーマを独立したサブ問いに分割し、explorer エージェントを Agent ツールで起動して調査を委譲します。メイン Codex が直接 Glob/Grep/Read/WebSearch/WebFetch で調べてはいけません。

起動ルール

• 最低1体起動: テーマの規模にかかわらず初回調査は必須
• 最大3体並列: テーマを独立したサブ問い（観点・情報源・対象）に分割できる場合は並列起動する。研究ワークフローは広く調べることが価値なので、分割できるなら積極的に並列化する
• model: sonnet（全 explorer 共通・固定）
• 情報源は Web + ローカルの両方: 外部の一次情報（WebSearch / WebFetch）と、手元のファイル・リポジトリ内の資料の両方を調査対象にする

プロンプトに必ず含めるパラメータ

• RUN_DIR=[パス]
• EXPLORATION_INDEX=NN（初回=01、並列起動時はスキル本体が 01/02/03 と割り振る）
• 「探索レポート本体は {RUN_DIR}/exploration-{NN}.md に書き出し、チャットには要約のみ返してください」
• 「これは研究調査です。実装・ファイル編集・git 状態変更は行わないでください。調査に徹し、外部の一次情報は必ず参照 URL を添え、記憶や推測で結論を埋めないでください」

プロンプトに必ず含める調査観点

• テーマに関する既知の事実・定説・データ（一次情報の出典付きで）
• 対立する見解・論争点・未解決の問い
• 関連する先行事例・類似ケース（ローカルの資料・コードにあれば含める）
• 情報の確実性（一次ソースか二次ソースか、どこまで裏が取れているか）

追加調査

初回レポートで不明点があれば追加で explorer を起動してよい（回数上限なし）。追加探索時は EXPLORATION_INDEX を既存 {RUN_DIR}/exploration-*.md の最大値+1 に設定する。

---

ステップ 2: 集約 + 調査結果ゲート（オーケストレーター, Opus）

2-1: 集約（サブに委譲せず、スキル本体自身が行う）

全 {RUN_DIR}/exploration-*.md を Read し、スキル本体（メイン Codex, Opus）が探索結果を1本に統合する。統合時に以下を行う:

• 複数 explorer が重複して報告した事実は1つにまとめる
• 出典のある事実と、出典が弱い/推測混じりの情報を仕分ける
• explorer 間で食い違う記述があれば「対立点」として明示する（潰さない）

集約結果を {RUN_DIR}/synthesis.md に Write する。フォーマット:

## 集約結果: [研究テーマ]

### 確定的な事実（出典あり）
- [事実] — 出典: [URL / ファイルパス]

### 不確実・出典が弱い情報
- [情報] — [なぜ不確実か]

### explorer 間の食い違い（該当する場合）
- [論点]: explorer-01 は X、explorer-02 は Y

### 調査で埋まらなかった空白
- [まだ分かっていないこと]

2-2: 調査結果ゲート（ユーザー確認・1回）

集約結果の要点を3〜6文で要約し、以下の選択肢を提示してユーザーの判断を受け取る。この方向のまま思考・仮説フェーズに進んでよいかを1回だけ確認する（探索方向のズレを早期に止めるため）:

• (A) この方向で思考・仮説へ進む: ステップ 3 へ
• (B) 追加調査: 不足観点を指定してもらい、ステップ 1 に戻って explorer を追加起動する
• (C) 方向修正: テーマの焦点・スコープを修正してステップ 1 からやり直す

ユーザーの選択と（あれば）追加指示を {RUN_DIR}/user-decisions.md に追記する（ファイルがなければ作成）。

本ゲートは探究の方向を決める分岐なので、対話実行では Auto mode でもユーザー応答を待つ。ただし応答が得られない無人実行（cron / CI / 上位エージェントからの自動起動 / smoke test 等）と判明した場合は、デッドロックを避けるため既定 (A) で継続し、user-decisions.md に「無人実行のため (A) を自動選択」と記録する。以降（思考・仮説）はゲートを挟まず自律で進める。

---

ステップ 3: 思考フェーズ（thinker, Fable）

thinker エージェントを Agent ツールで起動する。

• model: fable
• プロンプト:
  • RUN_DIR=[パス]
  • SYNTHESIS_PATH={RUN_DIR}/synthesis.md
  • THINKING_INDEX=01
  • 研究テーマ（$ARGUMENTS）
  • 「集約結果を構造的に分析し、論点・パターン・因果関係・論理構造を抽出してください。新規情報の収集はせず、思考レポート本体は {RUN_DIR}/thinking-{THINKING_INDEX}.md に書き出し、チャットには要約のみ返してください」

思考レポート要約を受け取る。

ℹ️ thinker は思考の副産物としてほぼ必ず「追加調査が必要な論点」を挙げる（考えるほど新しい問いが見えるため）。既定はそれらを最終サマリーの「未解決の問い」に繰り越して仮説フェーズへ進むこと。ステップ 1 への差し戻しは例外であり、挙がった不足が「仮説を1つも立てられないほど致命的」なときに限って行う。

差し戻す場合のみ、無限ループを避けるため RESEARCH_LOOP_COUNT を 0 から数え、追加調査は最大 2 回まで。上限に達したら、埋まらなかった情報を「未解決の問い」に明記して仮説フェーズへ進む。

---

ステップ 4: 仮説フェーズ（hypothesizer, Opus）

hypothesizer エージェントを Agent ツールで起動する。

• model: opus
• プロンプト:
  • RUN_DIR=[パス]
  • THINKING_PATH={RUN_DIR}/thinking-{最新 THINKING_INDEX}.md
  • SYNTHESIS_PATH={RUN_DIR}/synthesis.md
  • HYPOTHESIS_INDEX=01
  • 研究テーマ（$ARGUMENTS）
  • 「思考レポートをもとに検証可能な仮説を複数立て、各仮説に根拠・検証方法・反証条件・確信度を添えてください。仮説レポート本体は {RUN_DIR}/hypotheses-{HYPOTHESIS_INDEX}.md に書き出し、チャットには要約のみ返してください」

仮説レポート要約を受け取る。

---

ステップ 5: 研究レポートの統合（RUN_DIR）

集約・思考・仮説を 1 本で完結する研究レポートに統合し、プロジェクトローカルの見やすいパス（後述「出力先」）に Write する。

自己完結の原則（最重要）

このレポートは single source of truth。読者が中間ファイル（synthesis / thinking- / hypotheses-）を一切開かなくても、この 1 本だけで事象・根拠・仮説・優先順位・残課題まで意思決定できる**ように書く。

• 要約に痩せさせない。中間ファイルの結論だけを箇条書きで転記して終わらせない。事実・数値・根拠（コード位置 file:line / 出典 URL）・各仮説の「根拠 / 検証方法 / 反証条件 / 確信度」・トレードオフ・ロードマップの成功判定指標まで、判断に要る情報は省略せず転記する。長くなってよい（情報量を減らさない）。
• Overview（要約）を最上部に置く（下テンプレートの ## 0）。結論・規模・根本原因・最重要の一手を先に書き、詳細は後段に積む（逆ピラミッド）。ここだけ読めば全体が掴めるようにする。要約を末尾や中間に埋めない。
• 視覚構造（見出し階層・表・コードブロック・引用バッジ）で、長くても読めるようにする。
• 中間ファイルは「通常は参照不要」の付録扱いとし、パスだけ末尾に載せる。

テンプレート

{RUN_DIR}/synthesis.md / thinking-*.md / hypotheses-*.md を Read し、以下に詳細を転記する（見出しはテーマに応じて増やしてよい。痩せさせないことを最優先）:

# [研究テーマ] 研究レポート

_作成: YYYY-MM-DD_

> 📌 このファイルは single source of truth。中間成果物を読まなくても、この 1 本で意思決定できるように書いてある。

## 0. Overview（エグゼクティブサマリ）

- 結論・規模・根本原因・最重要の一手を数行で。**ここだけ読めば全体が掴める**ように。

## 1. 問い・背景

[研究テーマ・発端]

## 2. 調査で分かったこと（集約）

[synthesis.md の「確定的な事実（出典つき）」「不確実な情報」「食い違い」「空白」を、要点だけでなく根拠ごと転記]

## 3. 思考（分析・論点）

[thinking-*.md の因果構造・パターン・トレードオフ・論理の吟味を転記]

## 4. 仮説

[hypotheses-*.md の全仮説を「根拠 / 検証方法 / 反証条件 / 確信度」つきで転記。最有力仮説・検証ロードマップ（各手の成功判定指標つき）も含める]

## 5. 未解決の問い

[各段で残った空白を統合。何を・どの手段で確かめるか]

## 付録: 出典 / 中間成果物のパス

[主要出典 URL、および exploration-* / synthesis / thinking-* / hypotheses-* のパス（通常は参照不要）]

出力先

最終レポートはプロジェクトローカルの見やすいパスに置く。${PROJECT_ROOT}/.ai-pir-runs/** は git 追跡外の中間成果物置き場のため、中間成果物専用とし、人が読む最終レポートを既定でそこに置かない。

• 既定の出力先: {PROJECT_ROOT}/docs/research/{run_ts}-{run_feature}.md（例: docs/research/20260702-155242-foo.md）。docs/research/ が無ければ作成する（{PROJECT_ROOT} はステップ0で確定した値）。
• 中間成果物（exploration-* / synthesis / thinking-* / hypotheses-*）は RUN_DIR（${PROJECT_ROOT}/.ai-pir-runs/...）に残し、最終レポートの付録にそのパスを載せる。
• フォールバック: {PROJECT_ROOT} が git リポジトリでない・書き込み不可などでプロジェクト内に置くのが不適なときのみ、その旨を伝えて {RUN_DIR}/research-report.md に出す。
• 保存したら必ずフルパス（相対の省略形でなく開けるパス）を提示する。

---

ステップ 6: 最終サマリーの提示

以下の内容をユーザーに提示してください:

## Research 完了サマリー

### 問い
[研究テーマ]

### 研究レポート
[プロジェクトローカルのフルパス（ステップ5 の出力先。例: {PROJECT_ROOT}/docs/research/{run_ts}-{run_feature}.md）]

### 調査（要点）
- 起動した explorer: [N 体]
- 主要な事実: [1〜2文]

### 思考（要点）
- 中心的な論点/パターン: [1〜2文]

### 仮説
- 立てた仮説: [N 件]
- 最有力仮説: [1文]
- 確信度の分布: [高 X / 中 Y / 低 Z]

### 検証ロードマップ（最初の一手）
- [最有力仮説を確かめる最小ステップ]

### 未解決の問い
- [残った空白があれば]

### 作業ディレクトリ
{RUN_DIR}