research

リサーチセッションのオーケストレーション

複数の情報源を対象とする完全なリサーチセッションを実行します。分野を分類し、エージェントを並列で起動し、調査結果を統合して、書式付きのレポートを出力します。

使用しない場合

• 実行中のセッションで1つのサブトピックを深掘りする場合（tome:dig を使用）
• すでに集めた調査結果を統合する場合（tome:synthesize を使用）

ワークフロー

ステップ 1：分野を分類する

トピックに対して分野分類器を実行します。

from tome.scripts.domain_classifier import classify

result = classify(topic)
# result.domain, result.triz_depth, result.channel_weights

信頼度が 0.6 未満の場合、分類器は判断を保留し、拒否するのではなく絞り込みを行います。result.candidates にはキーワードによる根拠が見つかった分野が列挙され、triz_depth はそれらの候補のうち最も深いものになり、channel_weights は根拠の重みに応じてブレンドされます。複数の語彙にまたがるトピックこそクロスドメインチャネルの対象であるため、曖昧な場合は対象範囲を狭めるのではなく広げます。

候補リストとともに判断保留をユーザーに伝え、分野を上書きできるようにしてください。絞り込まれたプランを失敗と見なさず、分類器が推測を控えたものとして扱ってください。

candidates が空の場合、トピックに一致するキーワードはありません。絞り込み先がなく、エスカレーションによってノイズが増えると予算を浪費するため、低コストの2チャネルのプランを維持します。トピックが本当にリサーチ可能であれば、_DOMAIN_KEYWORDS の語彙に不足があります。分野を無理に割り当てるのではなく、その旨を伝えてください。

ステップ 2：リサーチを計画する

from tome.scripts.research_planner import plan

research_plan = plan(result)
# research_plan.channels, research_plan.weights, research_plan.triz_depth

ステップ 3：セッションを作成する

from tome.session import SessionManager

mgr = SessionManager(Path.cwd())
session = mgr.create(topic, result.domain, result.triz_depth, research_plan.channels)

ステップ 4：エージェントを起動する

Agent ツールを使って、リサーチエージェントを並列で起動します。 次の対応関係を使用してください。

チャネル	エージェントの種類	プロンプトに含める内容
code	tome:code-searcher	トピック
discourse	tome:discourse-scanner	トピック、分野、サブレディット
academic	tome:literature-reviewer	トピック、分野
web	tome:web-searcher	トピック、分野
triz	tome:triz-analyst	トピック、分野、triz_depth

ルール：

• research_plan.channels にあるすべてのチャネルを起動します。プランナーは各カードの min_depth に基づいてチャネルを選択します。code と discourse はすべての深さで、academic と web は medium から、triz は deep から起動します
• 対象となるエージェントはすべて、1つのメッセージで起動します（順次ではなく並列）

各エージェントのプロンプトには、次の内容を含めてください。

1. トピックの文字列
2. 分野の分類
3. チャネル固有のコンテキスト（discourse ではサブレディット、triz では triz_depth）。triz の場合は、PYTHONPATH="${CLAUDE_PLUGIN_ROOT}/src" python3 -m tome.channels.triz analyze --topic "<topic>" --domain <domain> も実行し、その JSON を含めてください。エージェントにはシェルがありません。ワークフローでチャネルを実行する際は、その JSON を trizAnalysis 引数として渡してください
4. tome.channels.cards の render_card(get_card(channel)) から取得した、チャネルのカード。このカードにはチャネルの制約事項が記載され、エージェント自身のファイルで説明されている形式を参照するよう案内されています。プロンプトで戻り値の形式を指定しないでください。エージェントはファイルよりプロンプトを優先するため、プロンプトで独自の形式を指定した結果、セッションのカナリア記録が失われたことがあります

上の表はカードの内容を再掲したものです。プランナーが起動対象を決める際に参照するのはカードであり、ドリフトテストによって両者の整合性が保たれます。

固有名詞。 質問で言及されている、または比較で順位付けされるすべての製品、プロジェクト、標準、手法を列挙し、そのリストをワークフローの entities 引数として渡します。ワークフローは各項目を、どのチャネルも扱っていない場合に検索し、残りを coverage.unsearched として返します。代わりにエージェントを直接起動する場合は、統合の前に同じ確認を自分で行います。調査結果で言及されていない各項目について tome:web-searcher を起動してください。検索せずに選択肢を採用したり除外したりしてはいけません。2026-10-05 のレポートでは、どのチャネルも Beartooth をたまたま扱っていなかったため、説明だけを根拠に除外していました。未検索の項目は、その名前を挙げてレポートの調査範囲のギャップに記載してください。

ステップ 5：収集と統合

すべてのエージェントから応答が返ったら：

1. 各エージェントの調査結果を Finding オブジェクトに解析します

2. 統合する前に、各エージェントが実際に検索した内容を記録します：

   from tome.synthesis.quality import parse_envelope
   
   for envelope in agent_envelopes:  # one per dispatched agent
       session.query_log.extend(parse_envelope(envelope))
   

   これにより、空のチャネルを読み取れるようになります。 Finding には見つかった内容を記録し、クエリログには 検索対象を記録します。このログがなければ、エラーが 発生したチャネルも、限られたトピックを検索した チャネルも、どちらも「調査結果なし」という同じ状態に なります。この手順を省略すると、レポート内のすべての チャネルが unknown と表示されます。

3. tome.synthesis.merger.merge_findings() を使って統合します

4. tome.synthesis.ranker.rank_findings() を使って順位付けします

ステップ 5b：検証して、続行するか終了する

from tome.synthesis.verifier import verify_context

check = verify_context(session, passes_run=n)  # max_passes default 2

CONTINUE には、作業内容とその理由が示されます：

• rerun：チャネルが失敗した、機能が低下した、記録が残っていない、または検索できたことを確認できない場合です。そのまま再度実行します。
• reformulate：対象領域が一致していない場合です。成果のあったチャネルの調査結果で使われている用語を使って、再度実行します。
• add：検索チャネルがまだ調べていない、候補となる未開拓領域がある場合です。そのチャネルを実行します。

該当するエージェントだけを実行し、そのエンベロープを同じセッションに追加して、もう一度統合と順位付けを行います。その後、passes_run を 1 増やして再検証します。STOP の場合はステップ 6 に進みます。パス数の上限（max_passes、既定値は 2）に達して STOP となった場合も、未完了の作業は一覧に残します。完了した検索として扱わず、未解決の課題として報告してください。各チェックの detail には、読み取った内容が示されます。判断が主観ではなく記録に基づく理由については、modules/stop-verifier.md を参照してください。

ステップ 6：出力を生成する

from tome.output.report import format_report, format_brief, format_transcript

# Default to report format
output = format_report(session)

# Save to docs/research/
output_path = f"docs/research/{session.id}-{slug}.md"

セッションの状態を保存します：

mgr.save(session)

ステップ 7：結果を提示する

ユーザーに簡潔な概要を表示します：

• tome.synthesis.frontier.frontier_verdict(session) によるフロンティア判定とその理由。これは「見つかった情報が少ないのは、そもそも情報が少ないからか、それとも検索がうまくいかなかったからか」という問いに対する、レポート自体の回答です。
• tome.synthesis.quality.channel_outcomes(session) による、チャネルごとの調査結果数と結果ステータス：ok、empty、error、rate_limited、degraded、unknown
• 関連性の高い調査結果のトップ 3 件
• 保存したレポートのパス
• tome.synthesis.frontier.frontier_stories(session) による調査ストーリー。各ストーリーは、根拠を伴う未解決の課題で、初期状態は undecided です。ユーザーに act、defer、decline のいずれかを選んでもらいます。ユーザーに代わって判断したり、ストーリーが選択される前にイシューを登録したりしないでください。検索記録だけでは、何にこのプロジェクトの時間を費やす価値があるか判断できません。defer が選ばれた場合は、セッション後も残るように minister:create-issue で登録します。act が選ばれた場合は、作業をすぐに開始し、イシューの登録は不要です。decline が選ばれた場合は、何も記録しません。

3 つの検索チャネルは、トピックを検索する前にポジティブコントロールを実行します。そのため、INCONCLUSIVE は「コントロールがまだ存在しない」という意味ではなく、具体的な状態を示すようになりました。これは次のどちらかを意味します。チャネルがカナリアチェックに失敗して検索できない状態であるか、コントロールを実行せずに検索したかです。どちらの場合も判定の根拠に記載され、Research Stories にストーリーが生成されます。

triz はコントロールを実行せず、判定から除外されます。過去の作業を検索するのではなく類推を生成するため、その出力は公開済みの情報に関する根拠にはならず、調査範囲の集計にも含まれません。

正常に完了しなかったチャネルは、明確に示してください。2 つのチャネルがレート制限を受けたことを伝えずに「調査結果 3 件」と報告すると、読者は一部しか実行されていない検索結果を、そのトピックについての確かな調査結果だと受け取るおそれがあります。

続けて、対話形式での絞り込みを提案します： 「特定の領域を調べるには、/tome:dig "subtopic" を使ってください。」

エラー処理

• エージェントが失敗した場合は、残りのエージェントで続行します
• すべてのエージェントが失敗した場合は、エラーを報告し、手動での調査方法を提案します
• 統合の結果、調査結果が 0 件の場合は、空のレポートを生成せず、その旨を明記します
• 部分的な失敗があった場合も、セッションの状態を保存します

出力形式の選択

フラグ	形式	関数
(default)	レポート	format_report()
--format brief	要約	format_brief()
--format transcript	トランスクリプト	format_transcript()

終了条件

• エージェントを実行する前にドメインを分類する。確信度が 0.6 未満の場合は、続行する前にユーザーの確認を求める
• research_plan.channels 内のすべてのチャネルを実行し、その範囲外のチャネルは実行せず、 すべてを1つの並列メッセージで実行する
• 各実行プロンプトに、そのチャネルの render_card の出力を埋め込み、 独自の戻り値の形式を指定しない
• 各パスの後に verify_context を実行する。レポートは STOP が返された後にのみ作成し、 実行するパスは max_passes 以下とする
• rerun、reformulate、または add を伴う予算上限による STOP が発生した場合、空でない チャネル名を要約内で不足分として示す
• すべてのエージェントが成功したかどうかにかかわらず、統合後にセッションを docs/research/{session.id}-{slug}.md に保存する
• 関連度スコア上位3件の調査結果と、保存したレポートのパスをユーザーに表示する
• すべてのエージェントが失敗した場合はエラーを報告し、手動での代替手段を提案する。空のレポートは生成しない