| name | deep-lit-review |
| description | Orchestrated multi-agent deep literature review with iterative follow-up, citation graph traversal, and convergence-based stopping. Use when user says "deep lit review", "review the literature", "find all papers on X", "lit review agents", or needs comprehensive literature exploration beyond simple search. |
| argument-hint | ["topic-or-list-of-questions"] |
| — output | ["path"] |
| — max-rounds | ["N"] |
| allowed-tools | Agent, Read, Write, Glob, Grep, Bash(*), WebSearch, WebFetch |
Deep Literature Review — Orchestrated Multi-Agent
Input Parsing
Parse $ARGUMENTS for:
- Topic or questions: The research area or specific list of questions to investigate
— output: [path]: Where to save results (default: docs/lit_review/{date}-deep-review/)— max-rounds: [N]: Maximum follow-up iterations (default: 10)— agents: [N]: Number of initial parallel agents (default: 7)— model: [sonnet|haiku|opus]: Model for search agents (default: haiku)
File Structure
The skill creates two separate areas — agent-facing working files and human-facing reports:
{output_dir}/
├── workbench/ # Agent-facing (raw, machine-readable)
│ ├── agents/ # Each initial agent's working output
│ │ ├── {id}_{short_name}.md
│ │ └── ...
│ ├── follow_ups/ # Follow-up agent outputs
│ │ ├── f{round}_{id}_{topic}.md
│ │ └── ...
│ └── orchestrator_log.md # All decisions: what launched, why, what came back
│
├── reports/ # Human-facing (clean, distilled)
│ ├── per_stream/ # One page per research stream
│ │ ├── {stream_name}.md
│ │ └── ...
│ ├── synthesis.md # Cross-stream synthesis + direction recommendations
│ └── open_questions.md # What we still don't know
│
├── state.md # Live status dashboard
└── README.md # Overview for the human
Orchestration Loop
round = 0
WHILE round < max_rounds AND NOT converged:
IF round == 0:
For each agent, build its prompt by:
1. READ templates/agent_prompt.md (MANDATORY — do not write prompts from scratch)
2. Fill in {{QUESTION}}, {{CONTEXT}}, {{OUTPUT_PATH}}, {{REPORT_PATH}}
3. Pass the filled template as the agent's prompt
Launch initial batch of agents (parallel, haiku)
ELSE:
Launch follow-up agents using the same template-filling process
WAIT for agents to complete
REVIEW each agent result:
Read TL;DR section only (Level 1 review)
For each stream, decide:
DEEPEN — promising lead not fully followed
→ follow-up agent on specific sub-question
EXPAND — discovered sub-field none of the streams cover
→ new agent with new question
MERGE — two streams found overlapping territory
→ one follow-up synthesizing both
RESOLVE — two streams contradict
→ targeted agent to find deciding evidence
CLOSE — question answered with sufficient confidence
UPDATE state.md with decisions
CHECK convergence (see CONVERGENCE CRITERIA below)
round += 1
AFTER loop exits:
Launch SYNTHESIS AGENT (reads all workbench files, writes reports/)
Update README.md with final status
Convergence Criteria
Quantitative (measured via OpenAlex + search results):
- New paper rate: Track unique papers found per round. If last 2 rounds found <3 new relevant papers combined → converging
- Citation frontier exhausted: For each key paper, both its references AND citers have been checked. No unexplored high-citation nodes remain
- Cross-stream stability: Stream TL;DRs haven't changed substantively in 2 rounds
Qualitative (judged by orchestrator):
- All initial questions have either a confident answer or a documented "insufficient evidence"
- No unresolved contradictions between streams
- No high-priority expansion leads left unfollowed
Early stop triggers (can stop before max rounds):
- All streams reach CLOSED status
- 3 consecutive rounds with <2 new relevant papers total
- All expansion leads have been followed or deprioritized
Late stop protection (keep going even if seemingly converged):
- A key paper was found in last round that opens new direction → don't stop
- Two streams contradict and resolution agent hasn't run → don't stop
- A stream returned "nothing exists" but only tried 1-2 query formulations → verify before stopping
Citation Graph Traversal
Agents use OpenAlex API for programmatic citation traversal. Rate limit: 10,000 requests/window (~20 hours), $0.001/request.
API patterns (baked into agent prompts):
curl -s "https://api.openalex.org/works?search=QUERY&per_page=10&select=id,title,publication_year,cited_by_count,doi"
curl -s "https://api.openalex.org/works/OPENALEX_ID?select=title,referenced_works"
curl -s "https://api.openalex.org/works?filter=cites:OPENALEX_ID&per_page=10&sort=cited_by_count:desc&select=id,title,publication_year,cited_by_count"
curl -s "https://api.openalex.org/works?filter=openalex:ID1|ID2|ID3&select=id,title,publication_year,cited_by_count,doi"
Traversal strategy:
- Forward citations (who cites this?) → finds recent follow-up work
- Backward citations (what does this cite?) → finds foundational work
- OpenAlex for graph structure; WebFetch for reading related work sections (authors' contextual commentary)
- WebSearch for very recent preprints not yet indexed by OpenAlex
Model Allocation
| Task | Model | Rationale |
|---|
| Search agents (all rounds) | haiku | Sufficient for search + relevance judgment; avoids rate limits |
| Follow-up agents | haiku | Same — cost-effective for targeted queries |
| Synthesis agent | haiku | Cross-references all streams; runs in own context |
| Final review in main conversation | opus (parent) | User interaction, strategic decisions |
Tiered Reading (Context Management)
The orchestrator in the main conversation never reads full agent outputs. Instead:
Level 0: state.md only (~50 lines)
→ Enough to decide what to launch next
Level 1: TL;DR section of each agent file (~10 lines each)
→ Enough to review quality and decide DEEPEN/EXPAND/CLOSE
Level 2: Full agent file (~200+ lines)
→ Only for streams needing DEEPEN or RESOLVE
Level 3: Fetch actual paper
→ Only for papers pivotal to a decision
The synthesis agent gets its own fresh context and can read all Level 2 files.
