/cs-litreview

disable-model-invocation: true
name: "cs-litreview"
description: "/cs-litreview <research-question> — Academic literature orientation. Grill-me intake (question + framework + depth), free-lane recon (PubMed E-utilities + OpenAlex, keyless; Consensus MCP added only when connected), framework checkpoint, sequential budget-allocated searches (5/10/20), 8-section .docx research guide output. Sibling of /cs-pulse (research pack)."

/cs-litreview — Academic Literature Orientation

**Command:** `/cs-litreview <research question>`

The `cs-litreview` persona produces a strategically planned mini literature review as an 8-section `.docx` research guide.

When to Run

• Starting research on an unfamiliar field
• Writing a paper that needs grounding in current literature
• Mapping the "lay of the land" before committing to a research direction
• Want a curated reading list with key authors + foundational papers + gaps

When NOT to Run (search directly)

• Looking for ONE specific paper (just search PubMed/OpenAlex — or Consensus if you use it)
• Quick lookup with no need for synthesis
• Field you already know well and just need a recent papers list

Forcing Intake (3 Questions, One at a Time)

| Q | Asks | Default if forcing-choice | |---|---|---| | Q1 | Research question (1-2 sentences, specific) | refuses vague; "AI in medicine" gets pushed back once | | Q2 | Framework: PICO / SPIDER / Decomposition / Hybrid / You-pick | "you pick" (skill recommends from Q1) | | Q3 | Tentative depth: Quick (5) / Standard (10) / Deep (20) | re-confirmed at post-Phase-2 checkpoint |

What You Get

After Phase 0 intake + Phase 1 recon + Phase 2 framework + interactive checkpoint + Phase 3 searches:

**`research_guide_<topic>_<date>.docx`** with 8 sections:

1. **Topic Overview** — single tight paragraph 2. **Start Here — Priority Reading Order** — 5-7 hyperlinked papers (best-review → foundational → frontier → gap) 3. **How the Field Got Here** — chronological narrative + timeline table 4. **Sub-area Guides** — one per sub-area (4 parts each: synthesis / key papers / search terms / boolean strings) 5. **Key Research Groups** — top 3-5 authors/groups with representative papers 6. **Open Questions & Gaps** — methodological / population / conceptual 7. **Bibliography** — alphabetical, hyperlinked, every inline citation matches 8. **Audit Log** — search table + counts + search lane used (free / free+Consensus)

Interactive Checkpoint (Mid-Run)

After Phase 2 (framework selected, sub-areas generated), the skill **halts** with a forcing-options prompt:

Framework breakdown:
| {Component} | How it maps to your topic | Proposed sub-area |
|---|---|---|
| Population | ... | Sub-area 1: ... |
| Intervention | ... | Sub-area 2: ... |
| Comparison | ... | Sub-area 3: ... |
| Outcome | ... | Sub-area 4: ... |
| Cross-cutting | ... | Sub-area 5: ... |

Confirm depth (search lane: free — PubMed + OpenAlex, ~20 results per query per source):
  1. Quick scan (5 searches)
  2. Standard review (10 searches)
  3. Deep dive (20 searches)

Sub-area options:
  - Looks good — proceed
  - Adjust: add sub-area on [X]
  - Adjust: replace [Y] with [Z]
  - Restart with different framework

This is the **last cheap moment** to correct course before search budget is consumed. Skill refuses to start Phase 3 without explicit user choice.

Discipline (Research-Pack Convention)

• **One intake question per turn.** Never bundle.
• **Sequential search calls.** 1 q/sec rate limit. NEVER parallelize (any lane).
• **Lane check at session start** — if the Consensus MCP tools are not available, use the free lane; do not attempt tier detection. Lane reported at checkpoint.
• **Halt at checkpoint.** No Phase 3 without confirmation.
• **Source discipline** — cite only THIS session's search results. Training knowledge labeled `[Not from search]`.
• **Three-count tracking** — searches / unique papers / cited.
• **Retry once after 3s** — then log. 3 consecutive failures → stop.

Workflow

# Phase 0 intake (Q1-Q3 one at a time)
python ${CLAUDE_PLUGIN_ROOT}/skills/litreview/scripts/citation_tracker.py --action start --session NAME
python ${CLAUDE_PLUGIN_ROOT}/skills/litreview/scripts/framework_recommender.py --question "<Q1>"

# Phase 1 recon (1 free-lane search; record sent + received; add Consensus if connected)
python ${CLAUDE_PLUGIN_ROOT}/skills/litreview/scripts/free_search.py --query "<broad Q1>" --source both --max 20
# Phase 2 framework + sub-area generation
# CHECKPOINT — wait for user

# Phase 3 searches (sequential, 1 q/sec, budget per tier):
#   5/10/20 searches across sub-areas + review + era-gated + follow-up

# Phase 4 cross-search aggregation + DOCX
python ${CLAUDE_PLUGIN_ROOT}/skills/litreview/scripts/cross_search_aggregator.py --results-file results.json  # Phase 3 search results; format in the script docstring
# Generate DOCX via Node.js docx library
python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" output.docx  # zip-integrity check; then confirm required sections present

python ${CLAUDE_PLUGIN_ROOT}/skills/litreview/scripts/citation_tracker.py --action close --session NAME

Trigger Phrases (auto-invoke without /cs:)

• "litreview on [topic]"
• "literature review on [topic]"
• "I'm starting a literature review on X"
• "I'm writing a paper on X"
• "help me research X"
• "I'm doing research on X"
• "can you help me research X"

**Do NOT trigger for:** single one-off paper searches — that's a plain PubMed/OpenAlex (or Consensus) query.

Anti-Patterns Rejected

• Parallelizing search calls (any lane)
• Skipping the interactive checkpoint
• Padding thin results with training knowledge
• Defaulting to non-PICO without justification
• Citing papers in chat that didn't come from this session's searches
• Attempting Consensus plan-tier detection (deleted — the only check is whether the Consensus MCP tools are available)
• Treating Consensus as required (free lane is the defau