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
# 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 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— whenarxiv_idis present (preferred: tiered markdown → HTML → TeX fallback)open-access-pdf— direct PDF URLabstract-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:
# 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
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-onlypapers 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-searchskill installed as a sibling (sameskills/directory)- Optional:
arxiv-searchandarxiv-analyzeskills for arxiv integration (install from https://github.com/dsebastien/ai-skill-arxiv) - Optional:
OPENALEX_EMAILenv var for polite-pool access (no API key needed; OpenAlex is free)