| name | literature-review |
| description | Synthesize a related-work / literature-review section from the project's OWN library (references.bib + sources/ + vault) — thematic, gap-driven, calibrated, real citations only. Proposes concrete search directions for gaps without fabricating a single source. |
| user-invocable | true |
Literature Review
Core Rule
Synthesize only what is in the library. Never invent a citation, author, year, finding, or quantity. A literature review's deadliest failure is the model confidently asserting "prior work shows X \cite{plausible2021}" for a paper that does not exist. This skill works your references.bib + sources/ (+ vault/ if present) and nothing else. For what the library lacks, it emits search directions — what to look for — never a fabricated source to fill the hole.
When to Use
Invoke with /literature-review when:
- Drafting or revising the Related Work / Background section
- Grounding the Introduction's gap claim in real prior work
- Positioning your contribution against the field before submission
- Checking whether your library actually covers the themes your argument needs
Process
Phase 1 — Inventory the library
Before synthesizing anything, take stock:
- Count
references.bib entries; note which have full text or notes in sources/ (or a summary in vault/).
- Flag metadata-only entries — you have the citation but not the content. You may cite their existence but must not assert specific findings without the source.
- Report coverage:
N references / M with readable source / K metadata-only.
If the library is thin for the argument at hand, say so — do not paper over it with invented work. A 4-source "review" is a 4-source review.
Phase 2 — Cluster thematically
A literature review is an argument, not an annotated list ("Smith said X. Jones said Y."). Group the real sources by theme / method / finding / chronology and build a map. Example clusters for an LLM-agent paper:
- Tool-augmented agent frameworks
- Hallucination & faithfulness in LLM outputs
- Verification / self-correction methods
- Agent evaluation benchmarks
Phase 3 — Gap analysis (against the thesis)
Read MANUSCRIPT_MAP.md → Thesis / Contribution. Locate the gap the synthesis must set up: "the literature establishes A and B but not C, which is our contribution." Every theme should pull toward that gap. If a cluster does not serve the thesis, it is background, not related work.
Phase 4 — Draft the synthesis
Write the section in LaTeX:
- Every non-trivial claim carries a real
\cite{key} resolving in references.bib.
- Calibrated verbs —
\citet{ex2023b} reports / finds / observes, not proves. Match the verb to what the source licenses (see agent_docs/academic-style.md).
- One paragraph per theme, each ending by advancing toward the gap.
- Metadata-only claims get a
[verify: source not read] marker, never a confident assertion.
Tool-augmented agents reliably decompose multi-step tasks \citep{ex2023a},
yet their tool calls remain error-prone under distribution shift
\citep{ex2023b}. Proposed remedies emphasise post-hoc self-correction
\citep{ex2024c}; deterministic pre-execution gating remains unexplored.
Phase 5 — Coverage + search-direction report
For every theme that is thin or missing, emit concrete search directions — what to look for, not a fabricated paper:
- Keywords / queries to run (e.g. "constrained decoding tool use", "self-consistency verification agents").
- Venues & years likely to hold it (e.g. NeurIPS / ICLR / ACL 2023–2025).
- Citation chaining — follow the references/citations of a paper you already have (e.g. "backward-cite from
\cite{ex2023b}").
- Author follow-ups — later work by an author already in your library.
The loop stays honest: you fetch the result → ingest it (/lit-ingest if the vault module is installed, or add to references.bib + sources/) → re-run /literature-review. The skill never closes a gap by inventing a source.
Phase 6 — Verify
citation-gate.sh confirms every \cite resolves (run an edit, or check .hook-state/last_quality_gate.json).- Spawn the
fact-checker agent on the load-bearing claims to confirm the source supports the verb.
- Report the tally:
(synthesized from read sources / metadata-only / gaps with search directions).
Output Format
- The drafted section — LaTeX, real citations, calibrated, gap-directed.
- Coverage table — theme → # sources → read vs metadata-only → strength.
- Search directions — per thin/missing theme, the concrete leads above (no fabricated papers).
- Tally —
(synthesized / metadata-only / gaps).
Pairs With
vault/ + /lit-ingest (E1) — the ideal backing store; ingest fetched sources here, then re-run.fact-checker agent — verifies the synthesis against sources.citation-gate.sh — guarantees no dangling \cite./gap-finder — surfaces uncited/unsupported claims in the draft./claim-check — claim-by-claim audit once the section is written.
Common Rationalizations (all rejected)
- "I'm fairly sure there's a paper on X." → Emit a search direction, not a
\cite. Confidence is not a citation.
- "The library is thin, I'll round it out with well-known work." → No. Report the gap with search directions; let the author fetch real sources.
- "This source probably says X." → If you have not read it (metadata-only), mark
[verify]; do not assert the finding.
- "A review needs ~40 references, so I'll list plausible ones." → A review needs the references you actually have; the gap report tells you how to get the rest.
Notes
- Two modes: vault-backed (rich synthesis from
vault/ summaries + concepts) and bib+sources-backed (works references.bib + sources/ notes; more metadata-only flags).
- This skill drafts and reports; changing the contribution framing is a Protected Claim — confirm with the author.
- Reasoner-tier work (synthesis across many sources) — see
CLAUDE.md → Model Selection.
