Literature Review

---
name: literature-review
description: Run a living literature review — triage papers into a review matrix (relevance tiers, KEY flags, a keep-but-flag quality checklist), keep it reconciled with Zotero/citekeys, and optionally project it into an Obsidian vault as linked, filterable notes. Use when the user wants a paper triaged into their review ("add this paper", "triage this", "does this fit"), wants a review matrix set up for a project, wants the vault notes/graph regenerated from the matrix ("update my literature notes/graph"), or asks what the review holds ("how many papers use ⟨method⟩", "which papers share ⟨theme⟩").
---

# literature-review — a living review matrix, with optional generated Obsidian views

You operate a **living literature review**: one row per paper in a **review matrix** (the source of truth), and — when the project uses Obsidian — a **generated projection** of that matrix into per-paper notes, theme hubs, and a browsable graph. The scholar reads and judges; you draft, check, count, and keep the layers in sync. **Prime directive: flag, never guess; propose, never apply.** Classification calls (tier, KEY, in/out) are drafted by you and **approved by the user before any write**. Citation-integrity rules live in `../../docs/04-citation-integrity.md`; reading stays human (rule 5) — a row is drafted from the paper, never from memory.

**The backbone doctrine.** This skill ships the *backbone* — the workflow, the gates, the generated surfaces. Every specific — theme vocabulary, hub terms and their labels, study types, checklist items, tiers, the audit model — is **per-project, living in that project's `review-conventions.md`**, and is *expected* to differ between projects and to be re-tuned as a review matures. Never treat one project's specifics as defaults for another; when a new project starts, Mode 0 interviews the user afresh. Hub labels may carry example lists for glanceability (e.g. `Methods — Quantitative (e.g., QWK, ICC, MFRM etc.)`) — the label is the user's to word.

## Step 0 — load the project's own rules (always first)
Look for **`review-conventions.md`** in the project (search two levels deep). It defines: scope (in/out), tier definitions, the KEY rule, the quality checklist, the **controlled theme vocabulary**, hub terms, matrix location, and the vault wiring. **If it exists, it is the source of truth** over anything below. If it doesn't, offer Mode 0. (Template: `../../starter-kit/review-conventions-template.md`.) A project may also keep a richer legacy conventions file (e.g. a knowledge-base CONVENTIONS.md) — defer to it wherever the two overlap.

## Mode 0 — set up a project's review (once)
1. Copy the template to the project as `review-conventions.md`; interview the user to fill **scope in/out**, **tiers**, and a first **theme vocabulary** (keep it under ~10 entries — a controlled vocabulary is what keeps the graph readable; it can grow deliberately).
2. Create the matrix if none exists — a workbook or CSV whose header row carries the core columns: `# · Authors (Year) · Short focus · Folder · Theme · Primary use · Relevance · Construct link · Manuscript section · Read? · Key points / notes · Flags · Cite key`. (An existing matrix with these columns is adopted as-is — never restructure it.)
3. If the project writes in Obsidian: confirm the vault notes folder in the conventions, then offer a first Mode-2 projection.

## Mode 1 — triage a paper (the heart; triage-only, then STOP)
For one paper (PDF, DOI, citation) or a batch pre-screen:
1. **Read** what was given (full text via Zotero when available) — first the **publisher-notice check**: `python3 ../../starter-kit/notice_scan.py <pdf>` reads page 1 and the last page for a printed correction · corrigendum · erratum · expression of concern · retraction; a hit goes into Flags verbatim with its date and the drafted row proposes `record_state: corrected|retracted`, so the row starts in the right state instead of being "discovered" by the next radar sweep. Then the **reading-quality gate**: run `../../starter-kit/pdf_probe.py` on the PDF first — its verdict (TEXT-RICH / TEXT-SPARSE / IMAGE-ONLY / ENCRYPTED) plus its visual-read page list make extractability a *measured* fact and name the pages to render as images (an IMAGE-ONLY scan is read from rendered page images — that is the OCR; never triage from pretend-text). Then declare the **Read basis** on the drafted row: `full text ✓` / `text-only — results in Figure N not visible to me` / `abstract-only` / `scan, unread`. Text-mode reading cannot see figures; when a paper's key results live in figures, read the probe's flagged pages as rendered images before finalizing the row.
2. **In/out** per the conventions' scope; if OUT, recommend filing outside the matrix and stop.
3. **Dedup** against the matrix (Authors + Cite key columns) and Zotero (watch preprint↔published pairs).
4. **Draft the row** — every core column, in the matrix's exact order; `Theme` **must come from the controlled vocabulary** (if none fits, propose the new vocabulary entry as part of the approval, don't invent silently).
5. **Tier / KEY / cite-with-care** via the conventions' quality checklist — the checklist **flags, never excludes** (breadth is valued; weak studies are tracked and flagged, not dropped). One-line rationale for each call.
6. **Benchmark against the corpus**: corroborates / extends / contradicts / supersedes which existing rows; stronger or weaker evidence than the current KEY set.
7. **List downstream updates** (other tabs, synthesis sections, vault regeneration) — then **STOP and wait for approval**.
8. **On approval only**: back up the matrix (dated copy), append/write, re-sort per conventions, then **verify integrity** — the multiset of row contents must be identical before/after any re-sort; restore from backup on failure. Report what was written.

## Mode 2 — project the matrix into the vault (generate, don't hand-write)
Run `python3 ../../starter-kit/matrix_to_vault.py <matrix> --notes-dir <vault-notes-dir> --conventions review-conventions.md --dry-run` and show the user the report: papers, hubs and sizes, **unlisted themes** (flagged, never auto-added), and **hand-edited notes that would be skipped**. On approval, run without `--dry-run`. Facts the generator enforces (and you must respect):
- Notes are **named by citekey** (globally unique, Zotero-tied, vault-merge-safe) and carry a `generated-by: clas-literature-review` marker.
- A file **without the marker is never overwritten** — user edits win; the report lists skips.
- Hub links come only from the **controlled vocabulary** and the conventions' **hub terms** (term → hub mappings over the matrix's own wording). Anything unmatched is reported, exit code 2 — a flag for the user, not an error to fix silently.
- The matrix remains the source of truth; regeneration is the sync mechanism. Never edit generated notes to "fix" the review — fix the matrix (via Mode 1) and regenerate.
- **Regeneration hygiene:** renaming or retiring a hub/theme leaves the old generated note behind (the generator never deletes). After a vocabulary change, prune stale generated files yourself — delete only files carrying the `generated-by` marker, and report what was pruned.
- **Vault lint (on request or after any regeneration; report-only):** orphan generated notes (citekeys no longer in the matrix), broken wikilinks (links to notes that don't exist — including hand-written notes pointing at renamed hubs), and hub–matrix drift (a hub's member list vs the current matrix). Report findings; the user decides what to prune — the `generated-by` marker guard keeps hand-edited files safe as always.
- **Hub namespaces** (keep the axes orthogonal): `Theme — ⟨argument-home⟩` (one per paper, controlled) · **`⟨Family⟩ — ⟨specific method⟩`** for methods (e.g. `Quantitative — QWK`, `Qualitative — interviews`: the family is the *prefix*, so a graph Group searching "Quantitative" shows the whole family while each hub names one specific method — mixed-methods papers link to hubs in both families) · `AI tool — ⟨model⟩` · `Interface — API/GUI`. A paper *lives in* one theme but *uses* many methods/tools.
- Every run also (re)generates **`Review Dashboard.md`** — the reporting surface: corpus and flow counts, tier and read-status distributions, the ★ KEY register, the cite-with-care register, and theme/method/tool coverage tables, all wiki-linked. This is the note to show a supervisor or mine for a methods paragraph. Read it after each regeneration — its distributions surface data-hygiene findings (inconsistent status vocabulary, KEY inflation vs the project's own rule) that you report to the user, never silently fix.

## Mode 3 — ask-the-review (counts, slices, reconciliation — and evidence sweeps)
Two gears. **Matrix gear** (seconds): mine the matrix's own wording for counts and slices. **Evidence gear** (minutes, for questions the matrix can't answer — "how was ⟨X⟩ set up in each paper, with page numbers?"): identify the relevant papers from the matrix, then fan out **one parallel reader agent per paper** over the Zotero full texts. Reader discipline, non-negotiable: quotes verbatim (≤25 words); page numbers **derived from page markers embedded in the extracted text** (running headers/footers) — where markers are too sparse, say so and give a section heading + a short searchable phrase instead; **never invent a locator**; declare text-layer blindness (figures/boxes that don't extract). Compile the returns into a page-anchored **evidence report note** in the vault (propose-only; wikilinked citekeys), and report back anything the sweep caught about the *matrix itself* (a row overclaiming what its paper says) as a queued fix, never a silent one.
Answer "how many / which papers …" questions **from the matrix** (theme, tier, method/tool hub terms, read-status), always returning **citekeys** alongside author-year strings; for standing counts, point the user at the generated `Review Dashboard.md`. For submission-time checks, reconcile three ways — matrix Cite-key column ↔ `library.bib` ↔ draft `[@keys]` — and report gaps in both directions. Delegate reference *truth* (resolution, retractions) to the **`citation-integrity`** skill; this mode only reconciles membership.

## Mode 4 — second-model audit (highly recommended at milestones; propose-only)
**When to run:** strongly recommend it (a) before any submission or synthesis milestone — alongside the `citation-integrity` pass — and (b) after any large triage batch (~15+ new rows). It stays *optional in mechanism* because it needs the user's own paid API key with a second vendor (CLARK's core pipeline is free software, and some institutions restrict sending research notes to external AI services — surface that consideration once). The free, deterministic layers (dashboard counts, orphan/reconciliation checks) are not optional — they run as part of Modes 2–3 regardless.
An independent, *different-vendor* model re-judges every row against the project's own conventions — catching drift (KEY inflation, tier inconsistency, rows that contradict themselves) with failure modes different from the model that drafted them. Requires an `## Audit` section in the conventions (model pinned by exact ID + `key-env` naming the user's own environment variable — you never see or handle the key itself; if it isn't set, tell the user how to set it in their shell and stop).
1. **Dry-run first**: `python3 ../../starter-kit/review_audit.py <matrix> --conventions <file> --dry-run` — show the request plan and payload sizes. The plan line names the **endpoint** it would call, because the conventions' `- api:` key selects the request format (`chat` by default, or OpenAI's `responses`), and the report stamps it beside the model, effort and prompt version: the same prompt sent through a different API is a different run, so never change it mid-census.
2. **Pilot before census**: run `--limit 3` and report the measured token usage and spend from the report footer; extrapolate ×N/3 and get the user's go before the full run (`--only-key` audits just the ★ set).
3. Present the report's **disagreements as questions, never corrections** — the user adjudicates; accepted changes go through Mode 1's approval flow into the matrix, then regenerate (Mode 2). **Sort them by basis first**: row-internal factual inconsistencies are checkable; tier and ★ KEY disputes are **interpretation-class by nature** (relevance to *this* project's argument) — they belong to the user's expert-judgment pile, and no auditor tier settles them.
4. **Escalate, don't relitigate**: for disputes the user finds genuinely hard, re-run just those rows (`--citekeys`) on the frontier-tier model pinned as `manuscript-model:` in the conventions — the task-tiering doctrine in one move: the cheap tier screens the volume, the frontier tier gets the hard judgment calls, and the user still decides.
Boundaries: metadata-tier only (rows, not PDFs — a full-text audit is a future, sampled, opt-in tier); the audit checks consistency with the project's rules, it does not certify truth; reading stays human (rule 5).
Configuration lessons (measured 2026-07): pin `effort: low` for the census — factual notes are effort-stable while judgement verdicts soften at high effort (and cost ~2.7×); verdicts are more sensitive to **prompt version** than to effort, so treat cross-version flips as "borderline" evidence and always report the stamped prompt-version. `--effort`/`--citekeys` support targeted A/B re-runs.

## If Zotero MCP tools are present
Prefer the live library for metadata and full text at triage time; verify citekeys against pinned Citation Keys and the render-time `library.bib` (they can differ from ad-hoc exports — look keys up, never guess patterns). The matrix's Cite-key column is the bridge between the review and the citation pipeline: keep it populated, and treat a matrix row whose key is missing from `library.bib` as a **sync-gap finding to report**, not to silently fix.

## Lessons burned in (provenance)
Triage-only with a human approval gate, runtime-loaded project rules, the flag-never-exclude checklist, and backup + integrity-check around destructive writes follow the maintainer's own proven living-review workflow (field-neutralized). The generated-projection restraint — one default view, extra artifacts explicit-only, deterministic regeneration with an always-emitted skip/flag report — adapts patterns proven in the wider open-source scholar-toolkit ecosystem (ideas only; no code reuse; sources credited in the maintainer's external-sources register). The controlled theme vocabulary exists because free-text themes were demo-proven to sprawl (30 hubs for 85 papers).