---
name: literature-review
description: Run a literature review using paper search and primary-source synthesis. Use when the user asks for a lit review, paper survey, state of the art, or academic landscape summary on a research topic.
---

# Literature Review

Produce a grounded, source-cited survey of the state of the art on a topic. Output is a Markdown artifact in `outputs/` with a `.provenance.md` sidecar.

Derive a short slug from the topic (lowercase, hyphens, ≤5 words). All files in this run use the slug as a prefix.

## Subagent mapping

See `../_platform-mapping.md`. In short:

| Upstream role | Claude Code | OpenCode |
|---|---|---|
| `researcher` | `Task` tool, `subagent_type: scholar` or `general-purpose` | `task` tool, `scholar` or `general` agent |
| `verifier` | `Task` tool, `subagent_type: oracle` or `general-purpose` (with WebFetch) | `task` tool, `oracle` or `general` with `webfetch: allow` |
| `reviewer` | `Task` tool, `subagent_type: general-purpose` with review-only prompt | `task` tool, general agent with review-only prompt |

## Workflow

### 1. Plan

Write `outputs/.plans/<slug>.md`. Include:

- Key questions the review must answer
- Source types to search (arXiv papers, web, repos, conference proceedings)
- Time period (e.g. "last 3 years" or explicit year range)
- Expected section structure
- Task ledger (one row per sub-question; status = `pending` / `done` / `blocked` / `superseded`)
- Verification log (critical claims that will need citation verification)

Summarize the plan to the user in 2–3 sentences. Continue immediately unless the user asks for plan review.

### 2. Gather

**Narrow topic (2–3 obvious angles):** search directly yourself — no subagent needed. Use the `alpha-research` skill for paper search.

**Wide topic (broad survey):** dispatch 2–4 `researcher` subagents in parallel. Give each a brief written to `outputs/.plans/<slug>-T<N>.md` describing exactly what that subagent should cover. Each researcher writes its notes to `<slug>-research-<topic>.md` on disk — not returned inline.

Rules:
- No silent skipping — if a researcher can't cover an assigned question, it must mark the ledger entry `blocked` with the reason.
- No PDF parsing unless the user asked for it. Prefer metadata, abstracts, HTML docs.
- At least 3 distinct queries when researching directly, covering definition/history, mechanism, and current usage.

### 3. Synthesize

You (the lead) write the draft, not a subagent. Save to `outputs/.drafts/<slug>-draft.md`.

Separate clearly:

- **Consensus** — claims multiple sources agree on
- **Disagreements** — explicitly name the split and who sits where
- **Open questions** — what the field hasn't settled

Before handing to the verifier, sweep every strong claim against your verification log. Downgrade anything inferred or single-source-critical.

### 4. Cite

Dispatch the `verifier` subagent against `outputs/.drafts/<slug>-draft.md`. Task:

> Add inline citations to every claim using the research files as source material. Verify each URL is reachable. Write the complete cited brief to `outputs/.drafts/<slug>-cited.md`.

After the verifier returns, confirm on disk that `outputs/.drafts/<slug>-cited.md` exists. If the verifier wrote elsewhere, move the file into place.

### 5. Review

Dispatch the `reviewer` subagent against the cited draft. Task:

> Check `outputs/.drafts/<slug>-cited.md` for: unsupported claims, logical gaps, zombie sections, single-source critical findings, overstated confidence. Categorize findings as FATAL / MAJOR / MINOR. Write to `<slug>-verification.md`.

- Fix all FATAL issues before delivery. If you fix FATALs, run one more review pass.
- Note MAJOR issues under "Open Questions" in the final draft.
- Accept MINOR issues.

When applying reviewer fixes: small localized edits for 1–3 corrections; for larger rewrites, write `outputs/.drafts/<slug>-revised.md` instead of making one giant edit call.

### 6. Deliver

Copy the final candidate (`<slug>-revised.md` if it exists, else `<slug>-cited.md`) to `outputs/<slug>.md`.

Write `outputs/<slug>.provenance.md` next to it:

```markdown
# Provenance: <topic>

- **Date:** YYYY-MM-DD
- **Rounds:** <number of research rounds>
- **Sources consulted:** <count>
- **Sources accepted:** <count>
- **Sources rejected:** <dead / unverifiable / removed>
- **Verification:** PASS | PASS WITH NOTES | BLOCKED
- **Plan:** outputs/.plans/<slug>.md
- **Research files:** <list>
```

Before responding, verify on disk that both files exist. Do not stop at an intermediate cited draft.

## Charts and diagrams

- **Quantitative comparison across papers** — Mermaid bar chart, or CSV in `outputs/.notes/<slug>-data.csv`. No invented numbers.
- **Taxonomies / method pipelines** — Mermaid `graph TD`. Every figure needs a provenance-bearing caption.

## Final response

Brief: link the final artifact, the provenance sidecar, and list any blocked checks.
