literature-review

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: literature-review
description: Orchestrate a two-pass literature review for a research question. Phase 1 casts a wide net via scholar-search (and optionally arxiv-search), phase 2 the agent screens candidates by title+abstract, phase 3 the shortlist gets full-text analysis, phase 4 the agent writes a structured synthesis. Persistent session state lives in ./literature-reviews/<slug>/. Use when the user says "literature review", "survey the field", "research question", "what does the literature say about", or "systematic search".
license: MIT
compatibility: Requires Python 3.11+ (stdlib only), internet access to api.openalex.org, and the sibling scholar-search skill installed. Optionally integrates with arxiv-search and arxiv-analyze if those are installed in common locations. No API key required (OpenAlex is free); set OPENALEX_EMAIL for polite-pool access.
---

# Literature Review

Orchestrate a structured two-pass review. The script drives state management and data fetching; the agent drives the judgment calls (screening, synthesis). Each review is a persistent session — you can pause, resume, and revisit.

## Phases

```
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
```

Steps 5 and 6 are agent-driven (no new subcommand); the script's job is to set up the material.

## Usage

```bash
# 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]
```

## Session layout

```
./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
```

Everything is JSON except `final.md`. Sessions can be re-run (rerun `search` to refresh, redo `screen` to revise shortlist). Delete the session dir to start over.

## Workflow

### Phase 1: init
Capture the research question clearly. Good questions are specific: "how does X differ from Y under condition Z" beats "X and Y". If the question is vague, prompt the user to sharpen it before running init.

### Phase 2: search
Default limit 50. Use `--year` to scope recency, `--min-citations` to cut noise. Add `--include-arxiv` if arxiv-search is installed and you want preprint coverage the scholar index may lag behind on.

Script dedups by arxiv_id, doi, and lowercased title.

### Phase 3: screen (the agent does this)
Read `candidates.json`. For each paper, decide: include or exclude. Use the first 1-2 sentences of the abstract for fast scanning; drill into the full abstract only for ambiguous calls.

Explicit inclusion criteria help consistency:
- Does the paper addres