literature-review

文献レビュー

構造化された2パスレビューを実施します。スクリプトは状態管理とデータ取得を担い、エージェントはスクリーニングや統合などの判断を担います。各レビューは永続的なセッションとして保存されるため、中断、再開、再確認ができます。

フェーズ

1. init      Create session, capture the research question
2. search    Wide net across Semantic Scholar (+ arXiv optional), dedup
3. screen    Agent reads titles/abstracts/tldrs, marks keepers
4. fetch     Script produces a fetch plan (arxiv-analyze or PDF URL per paper)
5. [read]    Agent reads each shortlisted paper via the indicated strategy
6. [synth]   Agent writes the review: established findings, tensions, gaps

ステップ5と6はエージェントが担当します（新しいサブコマンドはありません）。スクリプトの役割は、資料を準備することです。

使い方

# 1. Start a session
python3 scripts/literature_review.py init \
    "what makes sparse autoencoders interpretable in practice" \
    [--out-dir /path/to/reviews]

# Returns: {"session": "./literature-reviews/what-makes-sparse-..", "slug": "..."}

# 2. Cast a wide net
python3 scripts/literature_review.py search <session-dir> \
    --limit 50 --year 2023-2026 --min-citations 5 \
    [--venue ICLR,NeurIPS] [--include-arxiv]

# 3. Agent reads candidates.json, picks keepers
python3 scripts/literature_review.py screen <session-dir> \
    --include "a3ec0b75...,2501.11120,10.48550/arXiv.2401.00032" \
    [--reasons-file keep-reasons.json]

# 4. Get the fetch plan
python3 scripts/literature_review.py fetch <session-dir>

# 5-6. Agent reads each paper and writes ./literature-reviews/<slug>/final.md

# Status check at any time
python3 scripts/literature_review.py status <session-dir>
python3 scripts/literature_review.py list-sessions [--out-dir /path]

セッションの構成

./literature-reviews/<slug>/
├── state.json         # phase, question, counters
├── candidates.json    # phase-1 output: full search results
├── shortlist.json     # phase-2 output: papers the agent kept + reasons
├── fetch_plan.json    # phase-3 output: per-paper read strategy
└── final.md           # phase-4 output: agent writes this

final.mdを除き、すべてJSON形式です。セッションは再実行できます（searchを再実行して最新の結果を取得し、screenをやり直して候補リストを修正できます）。最初からやり直すには、セッションディレクトリを削除してください。

ワークフロー

フェーズ1：init

研究課題を明確に設定します。良い課題は具体的です。「XとY」よりも「条件Zにおいて、XはYとどう異なるか」のほうが優れています。課題が曖昧な場合は、initを実行する前にユーザーに具体化を促してください。

フェーズ2：search

デフォルトの上限は50です。新しさを絞り込むには--yearを、ノイズを減らすには--min-citationsを使用します。arxiv-searchがインストールされており、学術論文インデックスでカバーが遅れているプレプリントも対象にしたい場合は、--include-arxivを追加します。

スクリプトはarxiv_id、doi、小文字に変換したタイトルを基準に重複を除去します。

フェーズ3：screen（エージェントが実施）

candidates.jsonを読み込みます。各論文について、採用するか除外するかを判断します。素早く確認するには、アブストラクトの最初の1～2文を読み、判断が難しい場合にのみ全文を確認します。

一貫性を保つには、採用基準を明確にすると効果的です。

• 論文は研究課題に直接取り組んでいるか？
• 方法や主張は、学びを得るのに十分具体的か？
• 掲載誌・会議、発表年、被引用数は基準を満たしているか？

採用する論文のIDをカンマ区切りで指定して、screenを実行します。任意で、採用した各IDに1行の理由を対応付けた--reasons-fileを渡せます。理由はshortlist.jsonと最終的な統合結果に引き継がれます。

候補リストの目標は10～25本です。これより少ないと網羅性に欠け、これより多いと統合が難しくなります。

フェーズ4：fetch

スクリプトはfetch_plan.jsonを生成します。採用した各論文について、最適な読み込み方法が示されます。

• arxiv-analyze — arxiv_idがある場合（推奨：階層的にMarkdown → HTML → TeXの順にフォールバック）
• open-access-pdf — PDFの直接URL
• abstract-only — 全文が入手できない場合。採用するかどうかはエージェントが判断します

フェーズ5：read（エージェントが実施）

取得計画にある各論文について、指定された方法で全文を取得します。主張、方法、結果、限界を抽出します。メモはメモリ内、またはセッションディレクトリ内の一時ファイルに保存します。

フェーズ6：synthesize（エージェントが実施）

次の構成でfinal.mdを作成します。

# Literature Review: <question>

## TL;DR
One paragraph. What does the literature say?

## Established findings
Claims multiple papers converge on, with citations.

## Active debates
Claims papers disagree about. Who holds each position, and on what grounds.

## Methodological patterns
Dominant approaches and their trade-offs.

## Gaps
What's unstudied, understudied, or inconclusive.

## Most important paper to read next
One paper. Why.

## Appendix: included papers
Table: title | authors | year | venue | one-line takeaway | full-text status

厳守事項

• 引用やTLDRを決して捏造しないでください。 shortlist.jsonにフィールドがない場合は、統合結果にその旨を記載します。
• 2パスのスクリーニングは必須です。 スクリーニングを省略して50本の全文をいきなり読むのは、トークンの浪費であり、品質の低下にもつながります（シグナル対ノイズ比が悪化します）。
• セッションの状態は、慣例として追記のみとします。 修正が必要な場合は、state.jsonをその場で編集するより、新しいセッションを作成してください。
• 候補リストの目標は約10～25本です。 少なすぎると網羅性に欠け、多すぎると扱いにくくなります。
• 読めなかった論文を明記してください。 abstract-onlyの論文は、全文を入手できなかった旨を添えてレビューに記載します。読んだふりをしてはいけません。

トークン予算

フェーズ	トークン数（概算）
search（アブストラクト付き検索結果50件）	15K-30K
screen（エージェントによるざっとした確認）	入力15K-30K、出力は最小限
取得計画	2K
read（arxiv-analyzeのMarkdown階層を使って15本）	150K-300K
統合	5K-15K

本格的なレビューには合計200K-400Kトークンが必要です。計画的に進めてください。コンテキストの予算が限られている場合は、フェーズを複数のセッションに分けてください。

最も重要なこと

statusレポートの最後には、状況の要約ではなく、現在のフェーズで最も効果の大きい次のアクションを必ず1つ記載してください。例：「フェーズ：スクリーニング済み（候補12本）。次のアクション：fetchを実行し、まず論文2501.11120から読み始めてください。候補リスト内の6本がこの論文を引用しているため、最初に読むことで残りの理解の土台になります。」

要件

• Python 3.11 以降（標準ライブラリのみ）
• scholar-search スキルが隣接する場所（同じ skills/ ディレクトリ）にインストールされていること
• オプション：arxiv との連携には arxiv-search と arxiv-analyze スキル（https://github.com/dsebastien/ai-skill-arxiv からインストール）
• オプション：ポライトプールへのアクセスには OPENALEX_EMAIL 環境変数（API キーは不要。OpenAlex は無料です）