# Literature Review

> 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"…

- **Type:** Skill
- **Install:** `agentstack add skill-dsebastien-ai-skill-scholar-literature-review`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dsebastien](https://agentstack.voostack.com/s/dsebastien)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dsebastien](https://github.com/dsebastien)
- **Source:** https://github.com/dsebastien/ai-skill-scholar/tree/main/skills/literature-review

## Install

```sh
agentstack add skill-dsebastien-ai-skill-scholar-literature-review
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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  \
    --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  \
    --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 

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

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

## Session layout

```
./literature-reviews//
├── 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 address the question directly?
- Is the method/claim specific enough to learn from?
- Is the venue/year/citation count above threshold?

Invoke screen with the comma-separated IDs of keepers. Optionally pass `--reasons-file` mapping each included ID to a one-line reason — these flow into `shortlist.json` and into the final synthesis.

Target shortlist size: 10-25 papers. Fewer and you're missing coverage; more and synthesis gets unwieldy.

### Phase 4: fetch
Script produces `fetch_plan.json`: for each shortlisted paper, the best way to read it:

- `arxiv-analyze` — when `arxiv_id` is present (preferred: tiered markdown → HTML → TeX fallback)
- `open-access-pdf` — direct PDF URL
- `abstract-only` — no full-text available; agent decides whether to keep

### Phase 5: read (agent-driven)
For each paper in the fetch plan, pull the full text using the indicated strategy. Extract: claim, method, result, limitation. Keep notes in memory or in scratch files inside the session dir.

### Phase 6: synthesize (agent-driven)
Write `final.md` with this structure:

```markdown
# Literature Review: 

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

## Hard rules

- **Never fabricate citations or TLDRs.** If a field is missing in `shortlist.json`, mark it as such in the synthesis.
- **Two-pass screening is not optional.** Skipping the screen phase and going straight to full-text reads for 50 papers is a token disaster and a quality disaster (signal-to-noise).
- **Session state is append-only by convention.** If you need to revise, prefer creating a new session over editing state.json in place.
- **Target ~10-25 shortlist papers.** Fewer misses coverage; more is unwieldy.
- **Note what you couldn't read.** `abstract-only` papers are mentioned in the review with a note that full-text was unavailable — don't pretend you read them.

## Token budget

| Phase | Tokens (rough) |
|---|---|
| search (50 results with abstracts) | 15K-30K |
| screen (agent skim) | 15K-30K in, minimal out |
| fetch plan | 2K |
| read (15 papers via arxiv-analyze md tier) | 150K-300K |
| synthesis | 5K-15K |

Total: a real review burns 200K-400K tokens. Plan accordingly — split phases across sessions if your context budget is tight.

## The One Thing

End every `status` report with the single most impactful next action for the current phase — not a status summary. Example: "Phase: screened (12 shortlisted). **Next: run `fetch`, then start with paper `2501.11120` — it's cited by 6 others in your shortlist, so reading it first will anchor the rest.**"

## Requirements

- Python 3.11+ (stdlib only)
- `scholar-search` skill installed as a sibling (same `skills/` directory)
- Optional: `arxiv-search` and `arxiv-analyze` skills for arxiv integration (install from https://github.com/dsebastien/ai-skill-arxiv)
- Optional: `OPENALEX_EMAIL` env var for polite-pool access (no API key needed; OpenAlex is free)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [dsebastien](https://github.com/dsebastien)
- **Source:** [dsebastien/ai-skill-scholar](https://github.com/dsebastien/ai-skill-scholar)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-dsebastien-ai-skill-scholar-literature-review
- Seller: https://agentstack.voostack.com/s/dsebastien
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.