Literature Review

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:

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.