literature-survey

文献調査ループ

検索 → 抽出 → 対応付け → 拡張のループで、エビデンス／矛盾マトリックスを作成し、飽和状態に達した時点で停止します。成果物はマトリックス（主張 × 出典。各出典の見解を記録）です。フィードバック指標は、各ラウンドで加わる新たにマトリックスを変化させる出典の数です。この数が <patience> ラウンド連続で <min_new> を下回るまで拡張を続けます。一度きりの要約とは異なり、このループでは意図的に矛盾とギャップを探し、全体像が変化しなくなるまで糸口をたどり続けます。

調査の規律：各セル、つまりある主張に対する出典の見解は、実際の検索で取得した原文の抜粋によって裏付けられています。価値があるのは整った物語ではなく、文献がどこで一致し、意見が分かれ、沈黙しているかを誠実に示す地図です。

使用する場面

成果物が段落ではなくエビデンスの構造化された地図となる、複数の出典に基づく問いの調査に使用します。デフォルトでは、以下の完全な拡張→採用→マッピングのループを飽和状態に達するまで実行します。代替手段：ユーザーが簡単な調査だけを求めている場合は、ラウンド 0（シード）のみを実行し、シードマトリックスを返します。文献に照らして提出された提案書を評価する場合や、新たな仮説を提案する場合には使用しません。

セットアップ

バインディングを対話形式で解決します。 作業ディレクトリに loop.run.yaml が存在する場合は読み込み、値を1行で確認して、ループに進みます。それ以外の場合：Claude Code（AskUserQuestion ツールを利用可能）では、各バインディングの妥当と思われる値を推測して推奨オプションとして提示します。他のホストでは、引用符付きのプレーンテキストの質問で各項目を尋ねます。その後、loop.run.yaml（形式：examples/run.example.yaml）を書き込み、他のファイルを作成する前に、すべての値と文献のライブ／縮退ティアを確認します。

バインディング	意味	デフォルト	推測方法
<question>	範囲（年、下位分野、採用基準など）を含む調査の質問／トピック	—	ユーザーに尋ね、確認のため範囲を言い換えて伝えます
<eval_scale>	1ラウンドあたりの深さ（low／medium／high。下記参照）	medium	—
<matrix>	構造化出力マトリックス（schemas/matrix.schema.json に照らして検証）；survey.md も同じ場所に書き込みます	<sandbox_root>/matrix.json	—
<sandbox_root>	マトリックス、survey.md、台帳、文献キャッシュの保存先	./sandbox	—
<budget>	最大ラウンド数	6	—
<patience>	連続して「空振り」のラウンドがこの回数に達した時点で停止します	2	—
<min_new>	飽和のしきい値 — 新たに追加され、マトリックスを変更するソースがこの数に満たない場合、そのラウンドは「空振り」です	2	—

評価の深さダイヤル（<eval_scale> で1ラウンドあたりの上限を設定します — クエリ · 引用たどり · 全文読解 · 新規ソース採用上限）：

プリセット	クエリ · たどり	全文読解	新規ソース上限
low	2 · 0	0（スニペット／抄録のみ）	約6
medium (推奨)	4 · 1	1	約10
high	6 · ≥2	3	約16

文献ツールチェーン。 論文検索には、同階層にある literature-search スキルを使用します。<lit_skill_dir> を解決し（同階層にインストールされ、デフォルトは ~/.claude/skills/literature-search/）、<lit_py> = python3、<lit> = <lit_skill_dir>/tools/lit_search.py（tools/ セグメントに注意）を設定します。キャッシュを再利用するには、サブコマンドの後に --cache-dir <sandbox_root>/literature/.cache を追加します。ここで使用するサブコマンド：search "<q>"（ソースの発見）、snippet "<q>"（引用された一節 = セルの根拠）、cite <paperId> --direction references|citations|recommend（引用グラフをたどる）、fulltext <arxivId>（主要論文を1本、詳しく読む）。セットアップ時に <lit> --help が動作することを確認します。このループ自体が文献検索であるため、スキルが見つからない場合は黙って続行しないでください。ユーザーに伝えたうえで、スキルをインストールするか、すべての検索を WebSearch/WebFetch に切り替えてください（ランキング済みスニペットや引用グラフの展開は行わず、該当する根拠には source:"web" とタグ付けします）。

S2 キー（任意。処理をブロックしません）。 無料の S2_API_KEY があると、snippet／cite の信頼性が高まります。<lit> keys --init を実行し、表示された keys.env はユーザー自身に入力してもらいます。チャットにシークレットを貼り付けないでください。キーがない場合は、キー不要のプールに切り替わり、さらに WebSearch に縮退するだけです。キーの有無（真偽値のみ）を loop.run.yaml に記録します。

ループ

matrix = ソース + 主張 + ギャップ（初期状態は空）。dry = 連続して新規ソースが少ないラウンド数（初期値は 0）。<N> は 0 から開始します。

このチェックリストをコピーして、項目にチェックを付けてください。

• ラウンド 0 — シード。 <question> をサブトピックに分解し、それぞれに対して <lit> search を 1 回実行し、最も関連性の高いソースを採用します。それぞれの主要な主張を、逐語的な snippet とともにマトリクスに抽出し、明らかなギャップを記録します。
• 拡張。 カバーが最も薄いサブトピックと、未解消の矛盾やギャップを選びます。新しい <lit> search クエリを実行し、最も中心的な論文 1～2 件から引用グラフをたどります（<lit> cite）。<eval_scale> の上限を守ってください。
• 採用と抽出。 既存の sources と照合して重複を排除し（タイトル／ID で判定）、実質的に新しいソースごとに主要な主張と逐語的な snippet を抽出します。
• マッピング。 主張ごとに、関連する各ソースの立場を、該当する snippet とともに支持／反論／限定として記録します。ソースが支持と反論の両方を示す場合は is_contested を設定し、新たに明らかになった gaps を追加します。
• 飽和度の確認。 このラウンドで新たに追加され、マトリクスに変化をもたらしたソースの数を数えます。<min_new> 未満なら dry += 1、それ以外なら dry = 0 とします。次のラウンドでは、依然としてカバーが薄い部分に取り組みます。
• 記録。 ログに 1 行追加し、N = N + 1 とします。飽和状態（dry == <patience>）または <budget> に達したら停止します。

停止したら、<matrix>（schemas/matrix.schema.json に対して検証）と survey.md を作成します。survey.md は、ソースを引用しながら合意点（十分に裏付けられた主張）、見解の相違（意見が分かれている主張と各立場）、ギャップ（未解決の問い）に分けてまとめ、どのサブトピックが十分にカバーされ、どの部分が薄いかを明記した、誠実なカバレッジ注記を加えます。

マトリクスがスキーマ検証済みの成果物です。コンパクトな汎用例（schemas/matrix.schema.json を参照）：

{
  "question": "<question>",
  "sources": [{"key": "S1", "title": "...", "source": "s2", "id": "...", "year": 2022}],
  "claims": [{
    "claim_id": "C1", "statement": "...", "is_contested": true,
    "positions": [
      {"source_key": "S1", "stance": "supports",    "snippet": "verbatim passage ..."},
      {"source_key": "S3", "stance": "contradicts",  "snippet": "verbatim passage ..."}
    ]
  }],
  "gaps": ["open question the survey surfaced"]
}

source ∈ {s2, arxiv, web}；stance ∈ {supports, contradicts, qualifies}。

ログ

<sandbox_root>/ledger.tsv はタブ区切りとし、テキストにカンマを使わないでください。ヘッダー：

round	queries	new_sources	total_sources	new_claims	contested	dry

例：

round	queries	new_sources	total_sources	new_claims	contested	dry
0	4	7	7	9	1	0
1	5	5	12	4	2	0
2	4	1	13	0	2	1
3	4	0	13	0	2	2

新規ソース数の推移を報告し、最終的な数だけでなく、実際に飽和に達したことが読み手に分かるようにしてください。

制約

• 捏造しないでください。 すべてのソース、主張のスニペット、立場は、そのラウンドで取得した実際の <lit>／WebFetch の結果に基づくものとし、スニペットは逐語的に引用してください。{"error","fallback"} の場合は WebSearch／WebFetch を使用し、エビデンスに source:"web" とタグ付けしてください。マトリクスの信頼性は、逐語的なスニペットのルールによって担保されます。
• 意見の相違をマッピングし、丸めないでください。 ソース間に矛盾がある場合は、矛盾を明示して記録し（is_contested、両方のスニペット）、見解の相違を示すことが目的です。どちらか一方を勝者に選ぶことではありません。
• 飽和度は推測せず、測定してください — 新規ソース数が実際に <min_new> を下回ったことを理由に停止し、検索で到達できなかった範囲まで網羅したかのように示すのではなく、カバレッジを正直に報告してください。
• ソースの重複を排除してください。「新規ソース数」には、同じ論文の再発見ではなく、実際に追加されたソースを数えます。
• インストール禁止 — 関連する literature-search スキルは標準ライブラリのみを使用します。API キーを表示またはコミットしないでください（keys.env はプロジェクトルートで gitignore の対象のままにします）。サンドボックスは自己完結しており、../ による外部への移動は禁止です。
• 続行するかどうかを尋ねるためにループを中断しないでください。飽和、patience、または budget に達するまで実行してください。

停止条件

ループは次のうち最初に該当した時点で停止します。

• 飽和 — dry == <patience>（これらの各ラウンドで追加された新規ソース数が <min_new> 未満）。
• 予算 — N == <budget> ラウンドに到達。

必ず最後に、<matrix> のパス、統合結果（合意点／見解の相違／ギャップ）、ソース数、飽和状態を示す ledger.tsv の新規ソース数の推移、および薄い部分を明記したカバレッジ注記を記載してください。