Literature review
Work through six steps: scope, sweep, expand, verify, write, lint. The failure modes this skill exists to prevent are all silent — a fabricated DOI, a retracted headline result, a reading list dressed up as a synthesis — so each step below names the check that catches it.
1. Scope the request
Different phrasings want different deliverables:
| Request shape | Deliverable |
|---|---|
| "the paper for X" / "the original/seminal…" | one or two primary citations |
| "what's the evidence on X" | thematic synthesis |
| "compare A and B" | trade-off analysis ending in a recommendation |
| "where are the gaps" | named gaps, each anchored to what establishes it |
A vague lay query gets the scope a domain expert would default to, stated explicitly ("taking this as human RCT evidence; animal work is separate"). Clarify with the user only when the answer would change what you retrieve.
2. Sweep
Never write from recall. Recall chooses the framing and the search terms;
retrieval supplies every citation. Start with search_openalex /
crossref_lookup from this skill's runtime.py, a PubMed query, or any
literature connector advertised in the session (search_skills with
{"query":"literature PubMed Semantic Scholar bioRxiv ClinicalTrials"} finds
installed guidance; load matches with use_skill).
For a named-paper lookup, the target is the highly cited primary publication that later work cites — not a review of it, not a news piece. Even when you know the paper cold, resolving its DOI is one tool call; skipping it turns a citation into a claim about a citation.
3. Expand along the citation graph
Keyword sweeps miss two things systematically: the foundational paper a field
builds on, and the newest work that extends or contests your top hits. Take
the two or three most relevant results and run expand_citations(doi) — it
returns references (backward) and cited-by (forward) from OpenAlex. Fold the
on-topic finds back into the working set before drafting. A survey-grade
answer typically rests on fifteen or more distinct primary-paper DOIs; a
handful of reviews is a reading list.
The Python OpenAlex helpers raise on HTTP errors, timeouts, or malformed responses. Empty results are valid only after successful retrieval. If either citation direction fails, report the retrieval failure rather than treating the partial graph as complete. Do not convert an exception into an empty list.
4. Verify
Run verify_dois on everything you intend to cite. Distinguish registered,
not resolving, and unverified (ok=None, e.g. network failure) results. A
registered DOI still requires reading the paper to check whether it supports
the claim; a failed request is not evidence of fabrication. When you have
author/year/journal but no DOI, look it up; never
pattern-complete one. For surprising or high-profile findings, check
Crossref's update-to field: sensational papers are findable because they
were sensational, and some were retracted. When the requested paper does not
exist — the claim collapsed or was never established — say exactly that and
point at what the evidence actually shows, instead of substituting the
nearest-matching citation.
5. Write the synthesis
Organize by question or theme, never paper-by-paper. The value is the layer on top of the papers: what replicated, what didn't, where the field agrees on effect but splits on mechanism, which older result a newer one superseded. Two tests for the draft:
- First-sentence test. Read only each paragraph's opening sentence. In sequence they should form your argument; if they form a list of author names, you have an annotated bibliography.
- Bullet test. Consecutive lines starting
- Author Year showed…are a paragraph you haven't written. Bullets are for genuinely enumerable things (a reference appendix, a comparison table); the argument itself is prose.
Calibrate stated confidence to the evidence: a phase-3 RCT is stated plainly, a single-cohort finding is "one group reported", preprints are flagged as preprints, contested areas get both sides plus an honest "unresolved". Engage a contested premise rather than building on it.
Cite inline as [Author Year](https://doi.org/10.xxxx/...) so prose renders
as (Author Year) with the DOI in the href. URL-encode parentheses inside a
DOI as %28/%29. No numbered [1] references — they desync on reorder.
Headings are short noun phrases; with five or more topics, group under two or
three ## and demote the rest to ###.
6. Deliver and lint
The answer lives in the chat reply: open on the finding itself, lay out the evidence with inline DOIs, close on what remains open. For anything beyond a one-paper lookup, also save the full review to a project-relative Markdown file and link it at the end of the reply. Process narration — "all DOIs verified", "no retraction flags", "report saved" — belongs nowhere: not as opener, footer, or subtitle. Verification lives in the tool trace.
Before saving, run style_pass(draft) from runtime.py once on the full
markdown, fix what it lists in one editing pass, and save. It is a lint, not
a gate — do not loop on it. If style_pass is not defined in the kernel,
read this skill's runtime.py and exec it first.
