literature-review

Literature review

A literature question has two halves: finding the papers a domain expert would point to, and turning them into something more useful than a reading list — a synthesis that says what's established, what's contested, what's new, and where the holes are. Both halves can fail quietly and look like competent output until someone checks. This covers all of STEM — a machine-learning benchmark result, a distributed-systems protocol, a materials-synthesis route, and a clinical trial are all in scope, and the same discipline applies to each: retrieve before you write, ground every claim in a real record, never invent an identifier.

Read the request for what it's actually asking

"What's the paper for X" wants one or two specific citations; "what's the evidence on X" wants a synthesis; "compare A and B" wants a comparison, not two adjacent summaries; "where are the gaps" wants the gaps, with the survey as supporting material. A two-word lay query wants you to choose the scope a domain expert would default to and say so up front — "I'll read this as the transformer architecture paper, not the earlier attention mechanism it builds on" or "I'll take this as human RCT evidence; the animal literature is separate." Ask a clarifier only when the answer would genuinely change what you do.

Load the helpers

kernel.py in this skill's directory ships the retrieval and BibTeX helpers. There is no auto-injection: import the file by its path before using it, and the module has zero import-time side effects, so importing it costs nothing. From a Bash python invocation:

python - <<'PY'
import importlib.util, json
spec = importlib.util.spec_from_file_location("litrev_kernel", "${CLAUDE_SKILL_DIR}/kernel.py")
lr = importlib.util.module_from_spec(spec); spec.loader.exec_module(lr)
print(json.dumps(lr.verify_dois(["10.1145/3292500.3330701"]), indent=2))
PY

The public helpers are verify_dois, crossref_lookup, search_openalex, expand_citations, extract_dois, style_pass, resolve_published / resolve_published_all, dedupe_records, to_bibtex, and bibtex_tidy. Each call is a short python run that imports the module and prints JSON you read back. Two optional env vars tune the polite path: LITREVIEW_CONTACT_EMAIL (a real address you own; it enters the Crossref/doi.org polite pool, and until it is set no mailto: is sent and those requests are plain anonymous ones) and OPENALEX_API_KEY (raises OpenAlex's per-request budget; without it, OpenAlex calls go out unauthenticated and still work, subject to shared rate limits).