Literature

Literature Skill

Comprehensive academic literature workflow: discover, verify, organise, synthesise. Uses parallel sub-agents to search multiple sources, verify citations, and fetch PDFs concurrently.

> Web alternative: a lighter-weight version of this workflow runs at literature.example.com (packages/literature-workspace/) — keyword/file-upload search across biblio-sources + RefPile, with Sonnet-driven synthesis. Useful for collaborators (CF Access auth) or quick discovery sessions where you don't need vault sync, DOI hard-gating, or pipeline mode. Use the CLI skill when you need verified citations entering a .bib file or full Phase 5 synthesis with negative-evidence + cross-cluster analysis.

Hard Rules

Existential — block submission

These rules protect against the highest-cost failure modes. Violation invalidates the output.

1. Every citation must be verified to exist before inclusion. Never include a paper you cannot find via web search. Hallucinated citations are worse than no citations.
2. Every DOI must be programmatically verified before entering any .bib file. Sub-agents hallucinate plausible-looking DOIs that resolve to wrong papers (correct journal prefix, wrong suffix). The only reliable verification is scholarly scholarly-verify-dois with title-matching (Phase 3). A DOI that resolves to a different title is WRONG — treat it the same as a missing DOI.
3. The narrative synthesis ALWAYS lives at docs/literature-review/literature_summary.md. Never in paper/, paper-*/, or any Overleaf-synced directory. The paper/ directory is LaTeX-only. Markdown files there leak onto Overleaf and pollute the submission folder. Canonical filename: literature_summary.md (never _synthesis.md, synthesis.md, ad-hoc names).

---

Format — catch in review

These rules govern style and consistency. Violation produces fixable artefacts, not invalid claims.

1. Library-first. Always check Paperpile via paperpile search-library BEFORE any external search (Phase 1). Papers already held should be reused, not re-discovered.
2. Prefer the published version over preprints. If a paper is found on arXiv, SSRN, NBER, or any working paper series, search for a published journal/conference version via scholarly scholarly-search. Cite a preprint only if no published version exists. Enforced in Phase 2 (discovery), Phase 3 (verify), and Phase 4 (/bib-validate runs the full preprint staleness check).
3. Better BibTeX-format keys (e.g., Author2016-xx). When merging into an existing .bib, match existing keys. Never generate custom keys (AuthorYear, AuthorKamenica2017, etc.) unless explicitly told otherwise.
4. Match causal language to study design. Reserve causal verbs ("causes", "increases", "reduces") for designs that warrant causal inference (experiments, RCTs, credible quasi-experiments). For observational work use "is associated with", "predicts", "correlates with". Match the language to the design — not the authors' own claims. State disagreements precisely; do not flatten into "the literature is mixed."
5. Python: always uv run python. Never bare python, python3, pip, pip3.

> Known corrections (notation, method, citation, domain) are auto-injected from MEMORY.md via the LEARN-tag-routing protocol at invocation. See shared/learn-tag-routing.md.

---

Sprint Contract — Output Handoff

Protocol:

1. Pre-commitment (Phase 1.4 hook). Before generating the search plan, load the contract and paraphrase all 5 acceptance dimensions (D1 bib_completeness, D2 dedup, D3 coverage_attestation, D4 venue_aligned, D5 freshness). The paraphrase anchors output against the criteria rather than rationalising backwards. Skip in standalone mode where no downstream consumer is declared.

1. Self-check (Phase 4.3 hook). Before signalling pipeline completion, verify each dimension against its verification_rule. F1 (DOI verification fails, severity 90) or F2 (generated-key pattern with no DOI, severity 70) triggers producer_decision=revise_before_handoff — re-run Phase 3 verification, do not hand off.

1. Failure-mode cross-reference ([docs/reference/failure-modes.md](../../docs/reference/failure-modes.md)): contract F1 → taxonomy F1 fabricated citation (⛔ hard fail); contract F2 → taxonomy F4 invented bib key (⚠️ soft fail).

1. Override ladder. Round 1: re-run paperpile search-library + scholarly scholarly-verify-dois. Round 2: dispatch the claim-verify agent. Round 3: human review of the literature report.

Full schema + protocol: [docs/reference/sprint-contract-protocol.md](../../docs/reference/sprint-contract-protocol.md).

---

Modes

| Mode | Invocation | What it does | |------|-----------|-------------| | Standalone | /literature [topic query] | Search + verify + bib + synthesis. No project context needed. | | Pipeline | /literature | Full cycle: resolve project → search → verify → bib → bib-validate gate → vault sync → auto-commit. | | Deep | /literature --deep [query] | Standalone or pipeline + iterative gap-filling loop after Phase 3. Also triggered by "deep", "thorough", or "comprehensive review" in the query. | | Autonomous | /literature --autonomous (or -y) | Pipeline + run end-to-end without inter-phase pauses. Stackable with --deep. Hard gates still run; defaults used at every choice point. See "Autonomy" below. |

Mode detection: if the argument matches an atlas topic slug (~/vault/atlas/.md), run in Pipeline mode. Otherwise, Standalone. When in doubt, ask. Deep is a flag on either base mode. Autonomous is a flag on either base mode.

Pipeline mode — project context resolution: find the atlas topic file (find ~/vault/atlas/ -name ".md"), read frontmatter (title, project_path, outputs, connected_topics), resolve PROJECT="$(cat ~/.config/task-mgmt/research-root)/", locate the .bib file (ask if multiple). Report context and wait for confirmation before Phase 1 — unless --autonomous is set, in which case ambiguity is resolved by picking the largest .bib file in the project (typically paper-*/paper/references.bib or docs/literature-review/literature_summary.bib) and logging the choice.

Autonomy

Per the global --autonomous / -y convention defined in ~/.claude/rules/phased-work.md § "Autonomy flag convention". When set:

• No Phase 1.4 search-plan confirmation — emit the plan to the session log and proceed
• No Phase 2.2 dedup/rank pause — apply default filters and continue
• No Phase 3.5 deep-loop "continue?" prompts — run up to 3 iterations (default), stop when standalone: yes (skip 1.3, 1.4) | pipeline: yes | deep: yes

1.1 Session log + checkpoint

Literature searches are context-heavy. Always run /session-log to create a recovery checkpoint per [shared/checkpoint-resumability.md](../shared/checkpoint-resumability.md). Pipeline mode writes a JSON checkpoint after each phase so a crash resumes from the last completed phase, not from scratch.

1.2 Pre-search check

Find existing .bib files in project root, /references, /bib, /bibliography. Then:

1. Parse existing entries to avoid duplicates and understand context.
2. Identify gaps — note if the bibliography skews toward certain years/methods.
3. Compile the list of existing citation keys to pass to sub-agents.
4. Mandatory: check Paperpile. Call paperpile search-library for the topic (and paperpile get-items-by-label if a relevant label exists) to discover what the library already holds and reuse those citation keys. This is topic discovery, not a membership test. Membership/NEW tagging is decided authoritatively by DOI (paperpile lookup-by-doi) in Phase 3 Step 5 (the integrity gate), per [shared/reference-resolution.md](../shared/reference-resolution.md) § Membership Check — never default a paper to NEW because this topic search missed it. A topic-search hit here is a reuse hint; a topic-search miss proves nothing. If paperpile CLI is unavailable, log a warning and continue.
5. Resolve topic label via paperpile get-labels for the current topic. Used in Phase 4 sync reporting.
6. Check source availability via scholarly source-status --json (OpenAlex always; Scopus/WoS if API keys are set). Report so search agents know coverage.
7. Check scout-audit reports. Glob ~/vault/reports/scout/portfolio/**.md and **.md. If a recent (≤90 days) report exists, parse the Closest prior works and Most likely scoopers sections — feed authors/papers/groups directly to Phase 2 search agents as seeds. This avoids re-discovering what scout already surfaced.
8. Cold-start branch. If steps 4–7 yield directly when arXiv IDs are known — broad scholarly-search` returns high-citation noise (climate, hydrogen) on generic ML queries like "data shapley".

• For DOI-only known references, use Crossref via scholarly scholarly-verify-dois (faster + more reliable than search for targeted lookups; see [reference_mcp_scholarly_search.md](../../memory/referencemcpscholarly_search.md)).
• Flag synthesis output in literature_summary.md with a header banner: > **Phase-1 seed synthesis** — scaffold-derived references only; broader external discovery deferred to next iteration. This signals to downstream consumers that the bib is intentionally narrow.
• Skip Phase 2's full parallel search; jump straight to Phase 3 verification on the scaffold-named references.

Steps 4–7 are not optional — every literature search must check the library AND scout reports before external discovery. Step 8 fires conditionally and bypasses Phase 2 noise for cold-start projects.

For parsing scholarly CLI JSON output (mixes stderr log lines with stdout JSON), use the helper in [references/scholarly-output-parsing.md](references/scholarly-output-parsing.md).

1.3 Concept validation gate (pipeline mode only)

Run [shared/concept-validation-gate.md](../shared/concept-validation-gate.md) on the topic concept plan. If the plan fails (missing RQ, no theoretical framing, generic AI voice, standalone: yes | pipeline: yes | deep: yes (later expanded by 4.5 loop)

2.1 Parallel search

CLI pre-fetch via scholarly commands (search, similar-works, author-papers, arxiv-search, exa-search-papers) writing to /tmp/lit-search/*.json, then spawn 2-3 Explore agents in parallel (Google Scholar, bibliometric, S2/arXiv, domain-specific). Both scholarly and paperpile CLIs work inside sub-agents — pre-fetch or let agents shell out. Full CLI list, output paths, configuration: [references/phase-2-search.md](references/phase-2-search.md). Agent prompts: [references/agent-templates.md#phase-2-search-agent-templates](references/agent-templates.md#phase-2-search-agent-templates).

If CLI council enrichment fires here, run it as an additional parallel agent. If snowball enrichment fires, run it after primary search, before 2.2.

2.2 Deduplicate, classify, rank

1. Merge results from all search agents.
2. Remove duplicates — match on title similarity and DOI.
3. Field-framework extraction for each candidate: Setting / Population / Method / Data / DV / IV / Key finding / Mechanism / Boundary. Always run, even if partial — feeds ranking, gap analysis, synthesis, and /hypothesis-generation. Definitions: [references/field-framework.md](references/field-framework.md).
4. Rank by relevance, citation count, recency.
5. Select top N to verify (typically 25-30 candidates for 20-25 verified).
6. Assign batches of ~5 for verification.

If SciSciNet enrichment fires, run it on the ranked pool: adds disruption_score, novelty_score, is_hit_1pct flags; re-rank to boost hits and high-disruption papers.

---

Phase 3: Verify

> standalone: yes | pipeline: yes | deep: yes + iterative loop (4.5)

This phase IS the integrity gate per [shared/integrity-gates.md](../shared/integrity-gates.md). No reference may enter the .bib without passing here.

Seven-step protocol:

1. Batch DOI pre-verification via scholarly scholarly-verify-dois --json — title-match check is mandatory (off-by-one DOI suffix hallucinations are the dominant failure mode). One CLI call accepts up to 50 DOIs; if you have more, see Dispatch Rule below before splitting.
2. Find correct DOIs for flagged papers via Crossref API → scholarly-search → web search (in order of reliability).
3. Manual verification of remaining papers — spawn general-purpose agents in parallel, ~5 papers each. Template: [references/agent-templates.md#phase-4-verification-agent-template](references/agent-templates.md#phase-4-verification-agent-template).
4. Final DOI gate — re-run scholarly-verify-dois on all DOIs entering the .bib. Papers without DOIs get % NO DOI. Subject to the same Dispatch Rule.
5. Paperpile membership resolution (HARD — do not skip, do not infer from the Phase 1 topic search). For every verified DOI, run paperpile lookup-by-doi --doi --json to decide held-vs-NEW. This is the only authoritative membership test — paperpile search-library (Phase 1.2 step 4) is lossy topic discovery and a search miss is not evidence of absence. Batch ≥6 DOIs via a single Bash sub-agent that loops the lookups and returns a merged {doi: citekey-or-null} map (per the Dispatch Rule below). For each match, reuse the returned Paperpile citekey and pull the canonical entry with paperpile export-bib --citekeys --json; for each non-match, tag genuinely NEW and stage for import. Mark every assembled entry % IN PAPERPILE () or % NEW, and report the held/NEW split count. Full protocol: [shared/reference-resolution.md](../shared/reference-resolution.md) § Membership Check. Failure mode this closes: defaulting a held paper to NEW because the Phase 1 topic search missed it (incident 2026-06-03 — 6 held papers mislabelled NEW, caught only by the user; reused keys were diluted and NEW-staging over-counted).
6. Confidence grades — A (DOI + full metadata), B (stable identifier, no DOI), C (single non-canonical source).
7. Working paper inclusion test — include only if ≥2 of: high citations, established author, top venue, sole source for concept, verifiable forthcoming status.

Full protocol: [references/phase-4-verification.md](references/phase-4-verification.md).

Dispatch Rule (Steps 1, 4 & 5)

Per [_shared/cli-dispatch-policy.md](../_shared/cli-dispatch-policy.md): if Step 1 or Step 4 would require 2 or more scholarly-verify-dois calls (i.e. >50 DOIs total), dispatch a single Bash sub-agent that runs all batched calls and writes merged JSON to /tmp/lit-verify.json. Main context reads only the merged result, never the raw CLI output. Step 5 membership lookups follow the same rule: ≥6 paperpile lookup-by-doi calls dispatch to one Bash sub-agent returning a merged {doi: citekey-or-null} map to /tmp/lit-membership.json. For the bulk-threshold rationale, see ~/.claude/rules/subagent-prompt-discipline.md § Bulk-Operation Dispatch Rule.

3.5 Iterative deep loop (deep mode only)

Prerequisites: ≥5 verified papers. Each iteration: (1) gap analysis with era-gated checks for terminology/paradigm shifts, (2) targeted search via scholarly + Explore sub-agents, (3) merge + dedup, (4) verify new papers via the seven-step protocol above (including Step 5 Paperpile membership resolution). Convergence: 3 iterations OR standalone: 4.1–4.4, 4.6 | pipeline: all | deep: same as base mode

4.1 PDF download

Check Paperpile via paperpile search-library — papers with attached PDFs are SKIP, others DOWNLOAD. Spawn Bash agents in parallel (3-5 papers each) for the DOWNLOAD set. Best-effort — many papers are paywalled. Template: [references/agent-templates.md#phase-5-pdf-download-agent-template](references/agent-templates.md#phase-5-pdf-download

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: flonat
• Source: flonat/flonat-research
• License: MIT

Install and usage instructions live in the source repository linked above.