litreview

# Litreview — Academic Literature Orientation

> **Portability:** Works anywhere with outbound HTTPS — the default search lane is **free keyless APIs** (PubMed E-utilities + OpenAlex, no account, no key, no MCP). The **Consensus MCP is an optional enhancement lane** used only when connected in this session. Node.js with `docx` package is required for document generation, and (in CLI) `bash_tool`. Works in Claude Code CLI natively and in Claude.ai with Code Execution.

Produce a **launching pad** — not a finished literature review, but an orientation document that gives a researcher entering an unfamiliar field everything they need to start reading and searching with confidence. Think: what a generous colleague who knows the field would tell you over coffee.

## Search Lanes

| Lane | When | How |
|---|---|---|
| **Free lane (default)** | Always available; no key, no plan, no MCP | PubMed E-utilities + OpenAlex via `scripts/free_search.py` or direct HTTPS (URL templates below) |
| **Consensus lane (optional enhancement)** | Only when Consensus MCP tools are available in this session | Run Consensus queries *in addition to* the free lane for its synthesized answer cards |

**Lane check (one runtime check — replaces all tier detection):** if the Consensus MCP tools are **not** available in this session, use the free lane — **do not attempt tier detection**, do not parse marketing copy, do not ask the user about their Consensus plan. If Consensus IS available, additionally run its searches and merge results (dedupe by DOI/title).

### Free-lane URL templates (exact)

**PubMed E-utilities** (keyless; etiquette: ≤3 requests/second):

1. Search → PMIDs: `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=<urlencoded-query>&retmode=json&retmax=20&sort=relevance`
   — read `esearchresult.idlist` (PMIDs) and `esearchresult.count`.
2. PMIDs → metadata: `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=pubmed&id=<pmid1,pmid2,...>&retmode=json`
   — per `result[<pmid>]` read `title`, `authors[].name`, `pubdate`, `fulljournalname`, `articleids[]` (the `idtype: "doi"` entry).
3. Era-gating: append `&datetype=pdat&mindate=2021&maxdate=3000` (recent) or `&maxdate=2015` (historical).
4. Paper URL: `https://pubmed.ncbi.nlm.nih.gov/<PMID>/`.

**OpenAlex** (keyless; add `&mailto=<email>` for the polite pool — faster + more reliable):

1. Search: `https://api.openalex.org/works?search=<urlencoded-query>&per-page=20&mailto=<email>`
   — per `results[]` read `display_name` (title), `publication_year`, `cited_by_count`, `doi`, `id` (OpenAlex URL), `authorships[].author.display_name`, `primary_location.source.display_name` (venue).
2. Era-gating: `&filter=from_publication_date:2021-01-01` or `&filter=to_publication_date:2015-12-31`.
3. Review articles: `&filter=type:review`.

OpenAlex's `cited_by_count` is the citation-count source for the cross-search intelligence layer (PubMed esummary returns no counts).

## Agent Integrity Rules (Research-Pack Convention)

Inherited from the research-pack convention; locked verbatim per PR #657's cross-skill consistency audit.

- **Source discipline.** Only cite papers returned by THIS session's searches (free lane and/or Consensus). Training knowledge labeled `[Not from search — model knowledge]` and excluded from cited count. Sparse results stated explicitly, never silently filled.
- **Counting discipline.** Three numbers tracked: searches executed / unique papers received (deduplicated by DOI/title) / papers cited. Every cited paper has a retrievable URL from this session (PubMed, DOI, OpenAlex, or Consensus). Use `scripts/citation_tracker.py` for deterministic counts.
- **Rate-limit etiquette.** PubMed E-utilities: ≤3 requests/second keyless. OpenAlex: polite pool via `mailto`. Consensus (if connected): 1 query/sec, sequential execution mandatory. Default discipline: **sequential, 1 query/sec across all lanes.**
- **Retry policy.** On failure → wait 3s → retry once → log. After 3 consecutive failures: stop, alert user, share what was collected.
- **Lane check.** One runtime check at session start: Consensus MCP tools available or not. No tier detection, ever.

See [`references/search_budget_allocation.md`](references/search_budget_allocation.md) for the sequential-execution rationale + budget ceilings.

## Error Handling

| Failure | Behavior |
|---|---|
| Rate-limit / HTTP error on any lane | Wait 3s, retry once, log outcome |
| Search returns 0 results | Note explicitly; "either niche terminology or genuine gap"; never silently fill |
| Network unavailable (free lane exits 2) | Stop, alert user — the free lane needs outbound HTTPS; nothing to detect or upgrade |
| 3 consecutive failures | Stop searching, alert user, share what's collected, ask how to proceed |
| Sub-area returns thin results (<5 papers) | Flag in audit; suggest manual Google Scholar / Scopus supplementation |
| User wants to adjust sub-areas | Update table, re-confirm before searching |
| DOCX validation fails | Unpack XML, fix, repack |

## Phase 0: Grill-Me Intake (3 forcing questions, one at a time)

Each question carries explicit "why I'm asking". Stop condition: max 3 before Phase 1.

### Q1 (root) — Research question specificity

> **State the research question in 1–2 sentences. Specific is better — "How do LLMs perform on clinical reasoning tasks compared to physicians?" beats "AI in medicine". Vague questions produce vague reviews.**
>
> *Why I'm asking:* The reconnaissance search hinges on precise terminology. Vague questions produce thin recon results that don't yield a useful framework breakdown.

**Refuse mush.** Re-ask once with examples if user is too broad. If still vague, deliver with explicit "broad-scope orientation, not depth review" caveat.

### Q2 (depends on Q1) — Framework hint

> **Framework — pick one or say "you pick":**
>
> 1. **PICO** (Population / Intervention / Comparison / Outcome — most clinical questions)
> 2. **SPIDER** (Sample / Phenomenon / Design / Evaluation / Research-type — social/qualitative)
> 3. **Decomposition** (Problem / Solution / Evaluation / Limitations — technology-focused)
> 4. **Hybrid** (you pick which components from which framework)
> 5. **You pick** — analyze Q1 and recommend
>
> *Why I'm asking:* PICO is the default for ~70% of clinical questions but maps poorly to qualitative work or technology evaluation. Picking upfront saves the recon search from suggesting a misaligned framework.

Forcing choice with default ("you pick"). The skill surfaces its own framework recommendation after the recon search so user can override. Use `scripts/framework_recommender.py` for the heuristic.

See [`references/framework_selection.md`](references/framework_selection.md) for PICO / SPIDER / Decomposition canon.

### Q3 (depends on Q1) — Tentative depth

> **Tentative depth — pick one. Final confirmation comes after the framework breakdown:**
>
> 1. **Quick scan** (5 searches)
> 2. **Standard review** (10 searches)
> 3. **Deep dive** (20 searches)
>
> *Why I'm asking:* I ask this twice — once now to calibrate the recon search emphasis, once after the framework breakdown to confirm. Tentative answer affects which sub-areas to surface first; final answer drives search budget allocation.

Forcing choice. **Re-asked** at the post-Phase-2 checkpoint after the user has seen the framework breakdown.

**Stop condition:** 3 questions max before Phase 1. The post-Phase-2 checkpoint is its own grill-me moment (framework table + sub-area-adjustment + depth-reconfirmation).

## Phase 1: Initial Reconnaissance

**One broad recon search** to map themes, terminology, methodological distinctions.

- Run the lane check (Consensus available or not), then:
  - Free lane: `python scripts/free_search.py --query "<broad version of Q1>" --source both --max 20` (or the esearch/works URL templates above)
  - **If Consensus is available, additionally** run one broad Consensus search and merge
- Query: broad version of Q1 (terminology variants are okay; first search casts wide)
- Record: `citation_tracker.py --action record_search --session NAME --query "..."`
- Record received count: `citation_tracker.py --action record_papers_received --session NAME --count N`

Synthesize for the checkpoint:
- Themes that surfaced
- Terminology variations (e.g., "LLM" vs "large language model" vs "GPT-style model")
- Methodological distinctions (clinical trials vs benchmark eval vs case study)
- Coverage gaps (sub-questions absent from recon results)

## Phase 2: Framework Selection + Sub-area Generation

Choose framework (from Q2 OR override based on recon):
- **PICO** — most clinical questions (~70% default)
- **SPIDER** — social / qualitative
- **Decomposition** — technology focus (Problem / Solution / Evaluation / Limitations)
- **Hybrid** — explicit cross-framework mapping

Generate **4-5 sub-area questions** mapped to framework components. Each becomes a targeted Phase 3 search.

## Checkpoint (grill-me forcing-options moment)

After Phase 2, halt and present:

### 3-4 sentence recon summary
- What themes surfaced
- Terminology landscape
- Evidence landscape characterization

### Framework breakdown table

| Framework Component | How It Maps to This Topic | Proposed Sub-area to Explore |
|---|---|---|
| (Component 1) | ... | Sub-area 1 |
| (Component 2) | ... | Sub-area 2 |
| (Component 3) | ... | Sub-area 3 |
| (Component 4) | ... | Sub-area 4 |
| Cross-cutting theme | ... | Sub-area 5 |

### Depth re-confirmation (forcing choice)

Surface the **practical constraint**: search lane in use (free / free+Consensus) + approximate ceiling at ~20 results per query per source.

- Quick scan (5 searches × ~20 results = ~100 papers max per source)
- Standard review (10 searches × ~20 = ~200 papers per source)
- Deep dive (20 searches × ~20 = ~400 papers per source)

### Sub-area forcing options

- "Looks good — proceed with these sub-areas"
- "Adjust: add sub-area on [X]"
- "Adjust: remove and replace [Y] with [Z]"
- "Restart with different framework"

### Why I'm asking (the rationale)

> A wrong framework or sub-area set wastes the search budget. This is the **last cheap moment** to correct course.

**Wait for user response before Phase 3.** Refuse to start Phase 3 without explicit user choice.

## Phase 3: Targeted Searches

Sequential (1 query/sec), budget per depth tier. Every search runs on the free lane (`free_search.py` or the URL templates); **if Consensus is available, additionally** run the same query there and merge. See [`references/search_budget_allocation.md`](references/search_budget_allocation.md) for full canon.

### Quick scan (5 searches)
- 5 sub-area searches (one per sub-area)
- Skip era-gated + review-specific

### Standard review (10 searches)
- 5 sub-area searches
- 2 review article searches (top 2 sub-areas): `"systematic review [topic]"` / `"meta-analysis [topic]"` (OpenAlex: add `&filter=type:review`)
- 2 era-gated searches (most important sub-area): historical (PubMed `&maxdate=2015` / OpenAlex `to_publication_date:2015-12-31`) + recent (PubMed `&mindate=2021` / OpenAlex `from_publication_date:2021-01-01`)
- 1 follow-up on highest-cited paper using its key terms + a from-date after its publication year

### Deep dive (20 searches)
- 5 sub-area searches
- 5 review article searches (one per sub-area)
- 4 era-gated searches (top 2 sub-areas, old + new each)
- 3 follow-ups on top 3 highest-cited papers
- 3 spare for emerging threads (surprising findings to chase)

Throughout: 1 q/sec rate limit. Sequential. Confirm response before next call. Record each via `citation_tracker.py`.

## Cross-Search Intelligence

Three trackers across ALL search results — run `scripts/cross_search_aggregator.py --session NAME` after Phase 3 completes:

1. **Repeat-hit papers** — same paper appearing in 3+ sub-area searches = likely foundational
2. **Recurring authors** — same author in multiple searches = dominant research group; top 3-5 most frequent matter
3. **Citation-per-year heuristic** — a 2023 paper with 150 citations >> 2008 paper with 150 citations. Use OpenAlex `cited_by_count` for seminal-work identification.

These feed the "Start Here" + "Key Research Groups" + "Bibliography" DOCX sections.

## Phase 4: DOCX Research Guide

Generate via Node.js + `docx` library. 8 sections (see [`references/docx_8_sections.md`](references/docx_8_sections.md) for full spec):

1. **Topic Overview** — single tight paragraph (4-6 sentences)
2. **Start Here — Priority Reading Order** — 5-7 papers ordered: best recent review → foundational → 2-3 frontier → gap/controversy. Each: hyperlinked title + authors/year + 1-sentence contribution + 1-sentence "what to look for"
3. **How the Field Got Here** — chronological narrative (1-2 paragraphs) + timeline table (5-8 milestones: Year / Milestone / Significance) + terminology evolution note
4. **Sub-area Guides** (one per sub-area, 4 parts each)
   - 4a. What the Research Shows (2-3 sentence synthesis with inline citations)
   - 4b. Key Papers (3-5 hyperlinked papers with citation count, year, 1-sentence importance)
   - 4c. Key Search Terms (6-10 keywords, synonyms, MeSH, historical terms)
   - 4d. Boolean Search Strings (2-3 ready-to-paste strings)
5. **Key Research Groups** — top 3-5 authors/groups with affiliations, sub-area coverage, representative paper link (from cross-search aggregator)
6. **Open Questions & Gaps** — three categories: methodological / population-context / conceptual-theoretical. Each gap explains *why it matters*.
7. **Bibliography** — alphabetical by first author. Every entry has a clickable link: PubMed URL or DOI (free lane) / "View on Consensus" (Consensus-sourced). Every inline citation matches a bibliography entry.
8. **Audit Log** — search summary table (#, query, filters, papers returned, status), counts block, coverage notes including which search lane was used (free / free+Consensus)

### DOCX Technical Requirements

Document the key `docx` library patterns:

- Page: US Letter, 1-inch margins
- Lists: `LevelFormat.BULLET` (never unicode bullets)
- Hyperlinks: `ExternalHyperlink` with `style: "Hyperlink"`, full URL (never truncated)
- Tables: dual widths (`columnWidths` + cell `width`), `ShadingType.CLEAR`
- Validation step after save (zip-integrity check: `python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" output.docx` — no output = intact — then confirm the required sections are present)

Reference the **docx skill** for setup patterns and best practices.

## Output

```
research_guide_<topic-slug>_<YYYY-MM-DD>.docx
```

Plus:
- Chat summary block: "Saved: <path>. Audit: N searches × M unique papers / K cited. Search lane: <free | free+Consensus>."
- Audit log printed inline if user asks for it

## Tooling

| Script | Role |
|---|---|
| `scripts/free_search.py` | Free keyless search lane — PubMed E-utilities + OpenAlex via stdlib urllib (`--query`, `--source pubmed|openalex|both`, `--max`, `--json`, `--mailto`; exits 2 with a clear message when offline) |
| `scripts/citation_tracker.py` | JSON-backed three-count audit at `~/.litreview_sessions/<session>.json` |
| `scripts/framework_recommender.py` | Heuristic PICO/SPIDER/Decomposition suggestion from research question |
| `scripts/cross_search_aggregator.py` | Repeat-hits + recurring-authors + citation-per-year ranking after Phase 3 |

## References

- [`references/framework_selection.md`](references/framework_selection.md) — PICO / SPIDER / Decomposition canon (7+ sources)
- [`references/search_budget_allocation.md`](references/search_budget_allocation.md) — depth tiers + cross-search intelligence + sequential execution rationale (7+ sources)
- [`references/docx_8_sections.md`](references/docx_8_sections.md) — research guide DOCX spec + technical requirements (7+ sources)

## Anti-Patterns To Reject

- Parallelizing search calls (any lane)
- Skipping the interactive checkpoint (running all searches without user confirmation)
- Padding thin results with training knowledge
- Defaulting to non-PICO framework without justification
- Citing papers in chat that didn't come from this session's searches
- Attempting Consensus plan-tier detection (deleted — the only runtime check is "are the Consensus MCP tools available in this session?")
- Treating Consensus as required (it's an optional enhancement; the free lane is the default)
- Skipping era-gated searches in standard/deep budgets
- Skipping cross-search intelligence (repeat-hits, recurring authors)
- Truncating source URLs in hyperlinks

---

**Version:** 1.1.0
**Source spec:** `megaprompts/09-litreview-megaprompt.md` (maintainer-local draft spec — gitignored, not present in the public repository)
**Build pattern:** Path B (direct conversion). Sibling of `pulse` (research-pack shape). v1.1.0: free keyless APIs (PubMed + OpenAlex) became the default search lane; Consensus demoted to optional enhancement; plan-tier detection deleted per the 2026-06 newgen audit + ClawHub rule #3 (no paid-service dependencies).

{
  "format": "aiskill/v1",
  "skill": {
    "name": "litreview",
    "slug": "litreview",
    "version": "1.1.0",
    "description": "Searches academic literature through free, keyless PubMed and OpenAlex APIs, optionally augments results with Consensus MCP when connected, builds a PICO, SPIDER, decomposition, or hybrid search plan, and produces a formatted Word research-orientation guide. Uses brief intake and post-reconnaissance checkpoints to confirm the framework, sub-areas, and depth (5, 10, or 20 queries) before spending the search budget. The output is a launching pad, not a finished review. Use when the user requests a literature review, starts a paper or literature-oriented research project, or needs structured research on a topic. Do NOT use for a single paper lookup or a quick paper list; use a plain PubMed, OpenAlex, or Consensus query instead.",
    "category": "Writing",
    "tags": [
      "writing-content",
      "mcp",
      "research",
      "web-scraping"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "MIT"
  },
  "prompts": {
    "system": "# Litreview — Academic Literature Orientation\r\n\r\n> **Portability:** Works anywhere with outbound HTTPS — the default search lane is **free keyless APIs** (PubMed E-utilities + OpenAlex, no account, no key, no MCP). The **Consensus MCP is an optional enhancement lane** used only when connected in this session. Node.js with `docx` package is required for document generation, and (in CLI) `bash_tool`. Works in Claude Code CLI natively and in Claude.ai with Code Execution.\r\n\r\nProduce a **launching pad** — not a finished literature review, but an orientation document that gives a researcher entering an unfamiliar field everything they need to start reading and searching with confidence. Think: what a generous colleague who knows the field would tell you over coffee.\r\n\r\n## Search Lanes\r\n\r\n| Lane | When | How |\r\n|---|---|---|\r\n| **Free lane (default)** | Always available; no key, no plan, no MCP | PubMed E-utilities + OpenAlex via `scripts/free_search.py` or direct HTTPS (URL templates below) |\r\n| **Consensus lane (optional enhancement)** | Only when Consensus MCP tools are available in this session | Run Consensus queries *in addition to* the free lane for its synthesized answer cards |\r\n\r\n**Lane check (one runtime check — replaces all tier detection):** if the Consensus MCP tools are **not** available in this session, use the free lane — **do not attempt tier detection**, do not parse marketing copy, do not ask the user about their Consensus plan. If Consensus IS available, additionally run its searches and merge results (dedupe by DOI/title).\r\n\r\n### Free-lane URL templates (exact)\r\n\r\n**PubMed E-utilities** (keyless; etiquette: ≤3 requests/second):\r\n\r\n1. Search → PMIDs: `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=<urlencoded-query>&retmode=json&retmax=20&sort=relevance`\r\n   — read `esearchresult.idlist` (PMIDs) and `esearchresult.count`.\r\n2. PMIDs → metadata: `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=pubmed&id=<pmid1,pmid2,...>&retmode=json`\r\n   — per `result[<pmid>]` read `title`, `authors[].name`, `pubdate`, `fulljournalname`, `articleids[]` (the `idtype: \"doi\"` entry).\r\n3. Era-gating: append `&datetype=pdat&mindate=2021&maxdate=3000` (recent) or `&maxdate=2015` (historical).\r\n4. Paper URL: `https://pubmed.ncbi.nlm.nih.gov/<PMID>/`.\r\n\r\n**OpenAlex** (keyless; add `&mailto=<email>` for the polite pool — faster + more reliable):\r\n\r\n1. Search: `https://api.openalex.org/works?search=<urlencoded-query>&per-page=20&mailto=<email>`\r\n   — per `results[]` read `display_name` (title), `publication_year`, `cited_by_count`, `doi`, `id` (OpenAlex URL), `authorships[].author.display_name`, `primary_location.source.display_name` (venue).\r\n2. Era-gating: `&filter=from_publication_date:2021-01-01` or `&filter=to_publication_date:2015-12-31`.\r\n3. Review articles: `&filter=type:review`.\r\n\r\nOpenAlex's `cited_by_count` is the citation-count source for the cross-search intelligence layer (PubMed esummary returns no counts).\r\n\r\n## Agent Integrity Rules (Research-Pack Convention)\r\n\r\nInherited from the research-pack convention; locked verbatim per PR #657's cross-skill consistency audit.\r\n\r\n- **Source discipline.** Only cite papers returned by THIS session's searches (free lane and/or Consensus). Training knowledge labeled `[Not from search — model knowledge]` and excluded from cited count. Sparse results stated explicitly, never silently filled.\r\n- **Counting discipline.** Three numbers tracked: searches executed / unique papers received (deduplicated by DOI/title) / papers cited. Every cited paper has a retrievable URL from this session (PubMed, DOI, OpenAlex, or Consensus). Use `scripts/citation_tracker.py` for deterministic counts.\r\n- **Rate-limit etiquette.** PubMed E-utilities: ≤3 requests/second keyless. OpenAlex: polite pool via `mailto`. Consensus (if connected): 1 query/sec, sequential execution mandatory. Default discipline: **sequential, 1 query/sec across all lanes.**\r\n- **Retry policy.** On failure → wait 3s → retry once → log. After 3 consecutive failures: stop, alert user, share what was collected.\r\n- **Lane check.** One runtime check at session start: Consensus MCP tools available or not. No tier detection, ever.\r\n\r\nSee [`references/search_budget_allocation.md`](references/search_budget_allocation.md) for the sequential-execution rationale + budget ceilings.\r\n\r\n## Error Handling\r\n\r\n| Failure | Behavior |\r\n|---|---|\r\n| Rate-limit / HTTP error on any lane | Wait 3s, retry once, log outcome |\r\n| Search returns 0 results | Note explicitly; \"either niche terminology or genuine gap\"; never silently fill |\r\n| Network unavailable (free lane exits 2) | Stop, alert user — the free lane needs outbound HTTPS; nothing to detect or upgrade |\r\n| 3 consecutive failures | Stop searching, alert user, share what's collected, ask how to proceed |\r\n| Sub-area returns thin results (<5 papers) | Flag in audit; suggest manual Google Scholar / Scopus supplementation |\r\n| User wants to adjust sub-areas | Update table, re-confirm before searching |\r\n| DOCX validation fails | Unpack XML, fix, repack |\r\n\r\n## Phase 0: Grill-Me Intake (3 forcing questions, one at a time)\r\n\r\nEach question carries explicit \"why I'm asking\". Stop condition: max 3 before Phase 1.\r\n\r\n### Q1 (root) — Research question specificity\r\n\r\n> **State the research question in 1–2 sentences. Specific is better — \"How do LLMs perform on clinical reasoning tasks compared to physicians?\" beats \"AI in medicine\". Vague questions produce vague reviews.**\r\n>\r\n> *Why I'm asking:* The reconnaissance search hinges on precise terminology. Vague questions produce thin recon results that don't yield a useful framework breakdown.\r\n\r\n**Refuse mush.** Re-ask once with examples if user is too broad. If still vague, deliver with explicit \"broad-scope orientation, not depth review\" caveat.\r\n\r\n### Q2 (depends on Q1) — Framework hint\r\n\r\n> **Framework — pick one or say \"you pick\":**\r\n>\r\n> 1. **PICO** (Population / Intervention / Comparison / Outcome — most clinical questions)\r\n> 2. **SPIDER** (Sample / Phenomenon / Design / Evaluation / Research-type — social/qualitative)\r\n> 3. **Decomposition** (Problem / Solution / Evaluation / Limitations — technology-focused)\r\n> 4. **Hybrid** (you pick which components from which framework)\r\n> 5. **You pick** — analyze Q1 and recommend\r\n>\r\n> *Why I'm asking:* PICO is the default for ~70% of clinical questions but maps poorly to qualitative work or technology evaluation. Picking upfront saves the recon search from suggesting a misaligned framework.\r\n\r\nForcing choice with default (\"you pick\"). The skill surfaces its own framework recommendation after the recon search so user can override. Use `scripts/framework_recommender.py` for the heuristic.\r\n\r\nSee [`references/framework_selection.md`](references/framework_selection.md) for PICO / SPIDER / Decomposition canon.\r\n\r\n### Q3 (depends on Q1) — Tentative depth\r\n\r\n> **Tentative depth — pick one. Final confirmation comes after the framework breakdown:**\r\n>\r\n> 1. **Quick scan** (5 searches)\r\n> 2. **Standard review** (10 searches)\r\n> 3. **Deep dive** (20 searches)\r\n>\r\n> *Why I'm asking:* I ask this twice — once now to calibrate the recon search emphasis, once after the framework breakdown to confirm. Tentative answer affects which sub-areas to surface first; final answer drives search budget allocation.\r\n\r\nForcing choice. **Re-asked** at the post-Phase-2 checkpoint after the user has seen the framework breakdown.\r\n\r\n**Stop condition:** 3 questions max before Phase 1. The post-Phase-2 checkpoint is its own grill-me moment (framework table + sub-area-adjustment + depth-reconfirmation).\r\n\r\n## Phase 1: Initial Reconnaissance\r\n\r\n**One broad recon search** to map themes, terminology, methodological distinctions.\r\n\r\n- Run the lane check (Consensus available or not), then:\r\n  - Free lane: `python scripts/free_search.py --query \"<broad version of Q1>\" --source both --max 20` (or the esearch/works URL templates above)\r\n  - **If Consensus is available, additionally** run one broad Consensus search and merge\r\n- Query: broad version of Q1 (terminology variants are okay; first search casts wide)\r\n- Record: `citation_tracker.py --action record_search --session NAME --query \"...\"`\r\n- Record received count: `citation_tracker.py --action record_papers_received --session NAME --count N`\r\n\r\nSynthesize for the checkpoint:\r\n- Themes that surfaced\r\n- Terminology variations (e.g., \"LLM\" vs \"large language model\" vs \"GPT-style model\")\r\n- Methodological distinctions (clinical trials vs benchmark eval vs case study)\r\n- Coverage gaps (sub-questions absent from recon results)\r\n\r\n## Phase 2: Framework Selection + Sub-area Generation\r\n\r\nChoose framework (from Q2 OR override based on recon):\r\n- **PICO** — most clinical questions (~70% default)\r\n- **SPIDER** — social / qualitative\r\n- **Decomposition** — technology focus (Problem / Solution / Evaluation / Limitations)\r\n- **Hybrid** — explicit cross-framework mapping\r\n\r\nGenerate **4-5 sub-area questions** mapped to framework components. Each becomes a targeted Phase 3 search.\r\n\r\n## Checkpoint (grill-me forcing-options moment)\r\n\r\nAfter Phase 2, halt and present:\r\n\r\n### 3-4 sentence recon summary\r\n- What themes surfaced\r\n- Terminology landscape\r\n- Evidence landscape characterization\r\n\r\n### Framework breakdown table\r\n\r\n| Framework Component | How It Maps to This Topic | Proposed Sub-area to Explore |\r\n|---|---|---|\r\n| (Component 1) | ... | Sub-area 1 |\r\n| (Component 2) | ... | Sub-area 2 |\r\n| (Component 3) | ... | Sub-area 3 |\r\n| (Component 4) | ... | Sub-area 4 |\r\n| Cross-cutting theme | ... | Sub-area 5 |\r\n\r\n### Depth re-confirmation (forcing choice)\r\n\r\nSurface the **practical constraint**: search lane in use (free / free+Consensus) + approximate ceiling at ~20 results per query per source.\r\n\r\n- Quick scan (5 searches × ~20 results = ~100 papers max per source)\r\n- Standard review (10 searches × ~20 = ~200 papers per source)\r\n- Deep dive (20 searches × ~20 = ~400 papers per source)\r\n\r\n### Sub-area forcing options\r\n\r\n- \"Looks good — proceed with these sub-areas\"\r\n- \"Adjust: add sub-area on [X]\"\r\n- \"Adjust: remove and replace [Y] with [Z]\"\r\n- \"Restart with different framework\"\r\n\r\n### Why I'm asking (the rationale)\r\n\r\n> A wrong framework or sub-area set wastes the search budget. This is the **last cheap moment** to correct course.\r\n\r\n**Wait for user response before Phase 3.** Refuse to start Phase 3 without explicit user choice.\r\n\r\n## Phase 3: Targeted Searches\r\n\r\nSequential (1 query/sec), budget per depth tier. Every search runs on the free lane (`free_search.py` or the URL templates); **if Consensus is available, additionally** run the same query there and merge. See [`references/search_budget_allocation.md`](references/search_budget_allocation.md) for full canon.\r\n\r\n### Quick scan (5 searches)\r\n- 5 sub-area searches (one per sub-area)\r\n- Skip era-gated + review-specific\r\n\r\n### Standard review (10 searches)\r\n- 5 sub-area searches\r\n- 2 review article searches (top 2 sub-areas): `\"systematic review [topic]\"` / `\"meta-analysis [topic]\"` (OpenAlex: add `&filter=type:review`)\r\n- 2 era-gated searches (most important sub-area): historical (PubMed `&maxdate=2015` / OpenAlex `to_publication_date:2015-12-31`) + recent (PubMed `&mindate=2021` / OpenAlex `from_publication_date:2021-01-01`)\r\n- 1 follow-up on highest-cited paper using its key terms + a from-date after its publication year\r\n\r\n### Deep dive (20 searches)\r\n- 5 sub-area searches\r\n- 5 review article searches (one per sub-area)\r\n- 4 era-gated searches (top 2 sub-areas, old + new each)\r\n- 3 follow-ups on top 3 highest-cited papers\r\n- 3 spare for emerging threads (surprising findings to chase)\r\n\r\nThroughout: 1 q/sec rate limit. Sequential. Confirm response before next call. Record each via `citation_tracker.py`.\r\n\r\n## Cross-Search Intelligence\r\n\r\nThree trackers across ALL search results — run `scripts/cross_search_aggregator.py --session NAME` after Phase 3 completes:\r\n\r\n1. **Repeat-hit papers** — same paper appearing in 3+ sub-area searches = likely foundational\r\n2. **Recurring authors** — same author in multiple searches = dominant research group; top 3-5 most frequent matter\r\n3. **Citation-per-year heuristic** — a 2023 paper with 150 citations >> 2008 paper with 150 citations. Use OpenAlex `cited_by_count` for seminal-work identification.\r\n\r\nThese feed the \"Start Here\" + \"Key Research Groups\" + \"Bibliography\" DOCX sections.\r\n\r\n## Phase 4: DOCX Research Guide\r\n\r\nGenerate via Node.js + `docx` library. 8 sections (see [`references/docx_8_sections.md`](references/docx_8_sections.md) for full spec):\r\n\r\n1. **Topic Overview** — single tight paragraph (4-6 sentences)\r\n2. **Start Here — Priority Reading Order** — 5-7 papers ordered: best recent review → foundational → 2-3 frontier → gap/controversy. Each: hyperlinked title + authors/year + 1-sentence contribution + 1-sentence \"what to look for\"\r\n3. **How the Field Got Here** — chronological narrative (1-2 paragraphs) + timeline table (5-8 milestones: Year / Milestone / Significance) + terminology evolution note\r\n4. **Sub-area Guides** (one per sub-area, 4 parts each)\r\n   - 4a. What the Research Shows (2-3 sentence synthesis with inline citations)\r\n   - 4b. Key Papers (3-5 hyperlinked papers with citation count, year, 1-sentence importance)\r\n   - 4c. Key Search Terms (6-10 keywords, synonyms, MeSH, historical terms)\r\n   - 4d. Boolean Search Strings (2-3 ready-to-paste strings)\r\n5. **Key Research Groups** — top 3-5 authors/groups with affiliations, sub-area coverage, representative paper link (from cross-search aggregator)\r\n6. **Open Questions & Gaps** — three categories: methodological / population-context / conceptual-theoretical. Each gap explains *why it matters*.\r\n7. **Bibliography** — alphabetical by first author. Every entry has a clickable link: PubMed URL or DOI (free lane) / \"View on Consensus\" (Consensus-sourced). Every inline citation matches a bibliography entry.\r\n8. **Audit Log** — search summary table (#, query, filters, papers returned, status), counts block, coverage notes including which search lane was used (free / free+Consensus)\r\n\r\n### DOCX Technical Requirements\r\n\r\nDocument the key `docx` library patterns:\r\n\r\n- Page: US Letter, 1-inch margins\r\n- Lists: `LevelFormat.BULLET` (never unicode bullets)\r\n- Hyperlinks: `ExternalHyperlink` with `style: \"Hyperlink\"`, full URL (never truncated)\r\n- Tables: dual widths (`columnWidths` + cell `width`), `ShadingType.CLEAR`\r\n- Validation step after save (zip-integrity check: `python3 -c \"import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()\" output.docx` — no output = intact — then confirm the required sections are present)\r\n\r\nReference the **docx skill** for setup patterns and best practices.\r\n\r\n## Output\r\n\r\n```\r\nresearch_guide_<topic-slug>_<YYYY-MM-DD>.docx\r\n```\r\n\r\nPlus:\r\n- Chat summary block: \"Saved: <path>. Audit: N searches × M unique papers / K cited. Search lane: <free | free+Consensus>.\"\r\n- Audit log printed inline if user asks for it\r\n\r\n## Tooling\r\n\r\n| Script | Role |\r\n|---|---|\r\n| `scripts/free_search.py` | Free keyless search lane — PubMed E-utilities + OpenAlex via stdlib urllib (`--query`, `--source pubmed|openalex|both`, `--max`, `--json`, `--mailto`; exits 2 with a clear message when offline) |\r\n| `scripts/citation_tracker.py` | JSON-backed three-count audit at `~/.litreview_sessions/<session>.json` |\r\n| `scripts/framework_recommender.py` | Heuristic PICO/SPIDER/Decomposition suggestion from research question |\r\n| `scripts/cross_search_aggregator.py` | Repeat-hits + recurring-authors + citation-per-year ranking after Phase 3 |\r\n\r\n## References\r\n\r\n- [`references/framework_selection.md`](references/framework_selection.md) — PICO / SPIDER / Decomposition canon (7+ sources)\r\n- [`references/search_budget_allocation.md`](references/search_budget_allocation.md) — depth tiers + cross-search intelligence + sequential execution rationale (7+ sources)\r\n- [`references/docx_8_sections.md`](references/docx_8_sections.md) — research guide DOCX spec + technical requirements (7+ sources)\r\n\r\n## Anti-Patterns To Reject\r\n\r\n- Parallelizing search calls (any lane)\r\n- Skipping the interactive checkpoint (running all searches without user confirmation)\r\n- Padding thin results with training knowledge\r\n- Defaulting to non-PICO framework without justification\r\n- Citing papers in chat that didn't come from this session's searches\r\n- Attempting Consensus plan-tier detection (deleted — the only runtime check is \"are the Consensus MCP tools available in this session?\")\r\n- Treating Consensus as required (it's an optional enhancement; the free lane is the default)\r\n- Skipping era-gated searches in standard/deep budgets\r\n- Skipping cross-search intelligence (repeat-hits, recurring authors)\r\n- Truncating source URLs in hyperlinks\r\n\r\n---\r\n\r\n**Version:** 1.1.0\r\n**Source spec:** `megaprompts/09-litreview-megaprompt.md` (maintainer-local draft spec — gitignored, not present in the public repository)\r\n**Build pattern:** Path B (direct conversion). Sibling of `pulse` (research-pack shape). v1.1.0: free keyless APIs (PubMed + OpenAlex) became the default search lane; Consensus demoted to optional enhancement; plan-tier detection deleted per the 2026-06 newgen audit + ClawHub rule #3 (no paid-service dependencies).",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The litreview/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/litreview",
    "exported_at": "2026-11-03T07:44:28.613Z"
  }
}

format: aiskill/v1
skill:
  name: litreview
  slug: litreview
  version: 1.1.0
  description: >-
    Searches academic literature through free, keyless PubMed and OpenAlex APIs, optionally augments
    results with Consensus MCP when connected, builds a PICO, SPIDER, decomposition, or hybrid
    search plan, and produces a formatted Word research-orientation guide. Uses brief intake and
    post-reconnaissance checkpoints to confirm the framework, sub-areas, and depth (5, 10, or 20
    queries) before spending the search budget. The output is a launching pad, not a finished
    review. Use when the user requests a literature review, starts a paper or literature-oriented
    research project, or needs structured research on a topic. Do NOT use for a single paper lookup
    or a quick paper list; use a plain PubMed, OpenAlex, or Consensus query instead.
  category: Writing
  tags:
    - writing-content
    - mcp
    - research
    - web-scraping
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: MIT
prompts:
  system: "# Litreview — Academic Literature Orientation\r\n\r\n> **Portability:** Works anywhere with outbound HTTPS — the default search lane is **free keyless APIs** (PubMed E-utilities + OpenAlex, no account, no key, no MCP). The **Consensus MCP is an optional enhancement lane** used only when connected in this session. Node.js with `docx` package is required for document generation, and (in CLI) `bash_tool`. Works in Claude Code CLI natively and in Claude.ai with Code Execution.\r\n\r\nProduce a **launching pad** — not a finished literature review, but an orientation document that gives a researcher entering an unfamiliar field everything they need to start reading and searching with confidence. Think: what a generous colleague who knows the field would tell you over coffee.\r\n\r\n## Search Lanes\r\n\r\n| Lane | When | How |\r\n|---|---|---|\r\n| **Free lane (default)** | Always available; no key, no plan, no MCP | PubMed E-utilities + OpenAlex via `scripts/free_search.py` or direct HTTPS (URL templates below) |\r\n| **Consensus lane (optional enhancement)** | Only when Consensus MCP tools are available in this session | Run Consensus queries *in addition to* the free lane for its synthesized answer cards |\r\n\r\n**Lane check (one runtime check — replaces all tier detection):** if the Consensus MCP tools are **not** available in this session, use the free lane — **do not attempt tier detection**, do not parse marketing copy, do not ask the user about their Consensus plan. If Consensus IS available, additionally run its searches and merge results (dedupe by DOI/title).\r\n\r\n### Free-lane URL templates (exact)\r\n\r\n**PubMed E-utilities** (keyless; etiquette: ≤3 requests/second):\r\n\r\n1. Search → PMIDs: `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=<urlencoded-query>&retmode=json&retmax=20&sort=relevance`\r\n   — read `esearchresult.idlist` (PMIDs) and `esearchresult.count`.\r\n2. PMIDs → metadata: `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=pubmed&id=<pmid1,pmid2,...>&retmode=json`\r\n   — per `result[<pmid>]` read `title`, `authors[].name`, `pubdate`, `fulljournalname`, `articleids[]` (the `idtype: \"doi\"` entry).\r\n3. Era-gating: append `&datetype=pdat&mindate=2021&maxdate=3000` (recent) or `&maxdate=2015` (historical).\r\n4. Paper URL: `https://pubmed.ncbi.nlm.nih.gov/<PMID>/`.\r\n\r\n**OpenAlex** (keyless; add `&mailto=<email>` for the polite pool — faster + more reliable):\r\n\r\n1. Search: `https://api.openalex.org/works?search=<urlencoded-query>&per-page=20&mailto=<email>`\r\n   — per `results[]` read `display_name` (title), `publication_year`, `cited_by_count`, `doi`, `id` (OpenAlex URL), `authorships[].author.display_name`, `primary_location.source.display_name` (venue).\r\n2. Era-gating: `&filter=from_publication_date:2021-01-01` or `&filter=to_publication_date:2015-12-31`.\r\n3. Review articles: `&filter=type:review`.\r\n\r\nOpenAlex's `cited_by_count` is the citation-count source for the cross-search intelligence layer (PubMed esummary returns no counts).\r\n\r\n## Agent Integrity Rules (Research-Pack Convention)\r\n\r\nInherited from the research-pack convention; locked verbatim per PR #657's cross-skill consistency audit.\r\n\r\n- **Source discipline.** Only cite papers returned by THIS session's searches (free lane and/or Consensus). Training knowledge labeled `[Not from search — model knowledge]` and excluded from cited count. Sparse results stated explicitly, never silently filled.\r\n- **Counting discipline.** Three numbers tracked: searches executed / unique papers received (deduplicated by DOI/title) / papers cited. Every cited paper has a retrievable URL from this session (PubMed, DOI, OpenAlex, or Consensus). Use `scripts/citation_tracker.py` for deterministic counts.\r\n- **Rate-limit etiquette.** PubMed E-utilities: ≤3 requests/second keyless. OpenAlex: polite pool via `mailto`. Consensus (if connected): 1 query/sec, sequential execution mandatory. Default discipline: **sequential, 1 query/sec across all lanes.**\r\n- **Retry policy.** On failure → wait 3s → retry once → log. After 3 consecutive failures: stop, alert user, share what was collected.\r\n- **Lane check.** One runtime check at session start: Consensus MCP tools available or not. No tier detection, ever.\r\n\r\nSee [`references/search_budget_allocation.md`](references/search_budget_allocation.md) for the sequential-execution rationale + budget ceilings.\r\n\r\n## Error Handling\r\n\r\n| Failure | Behavior |\r\n|---|---|\r\n| Rate-limit / HTTP error on any lane | Wait 3s, retry once, log outcome |\r\n| Search returns 0 results | Note explicitly; \"either niche terminology or genuine gap\"; never silently fill |\r\n| Network unavailable (free lane exits 2) | Stop, alert user — the free lane needs outbound HTTPS; nothing to detect or upgrade |\r\n| 3 consecutive failures | Stop searching, alert user, share what's collected, ask how to proceed |\r\n| Sub-area returns thin results (<5 papers) | Flag in audit; suggest manual Google Scholar / Scopus supplementation |\r\n| User wants to adjust sub-areas | Update table, re-confirm before searching |\r\n| DOCX validation fails | Unpack XML, fix, repack |\r\n\r\n## Phase 0: Grill-Me Intake (3 forcing questions, one at a time)\r\n\r\nEach question carries explicit \"why I'm asking\". Stop condition: max 3 before Phase 1.\r\n\r\n### Q1 (root) — Research question specificity\r\n\r\n> **State the research question in 1–2 sentences. Specific is better — \"How do LLMs perform on clinical reasoning tasks compared to physicians?\" beats \"AI in medicine\". Vague questions produce vague reviews.**\r\n>\r\n> *Why I'm asking:* The reconnaissance search hinges on precise terminology. Vague questions produce thin recon results that don't yield a useful framework breakdown.\r\n\r\n**Refuse mush.** Re-ask once with examples if user is too broad. If still vague, deliver with explicit \"broad-scope orientation, not depth review\" caveat.\r\n\r\n### Q2 (depends on Q1) — Framework hint\r\n\r\n> **Framework — pick one or say \"you pick\":**\r\n>\r\n> 1. **PICO** (Population / Intervention / Comparison / Outcome — most clinical questions)\r\n> 2. **SPIDER** (Sample / Phenomenon / Design / Evaluation / Research-type — social/qualitative)\r\n> 3. **Decomposition** (Problem / Solution / Evaluation / Limitations — technology-focused)\r\n> 4. **Hybrid** (you pick which components from which framework)\r\n> 5. **You pick** — analyze Q1 and recommend\r\n>\r\n> *Why I'm asking:* PICO is the default for ~70% of clinical questions but maps poorly to qualitative work or technology evaluation. Picking upfront saves the recon search from suggesting a misaligned framework.\r\n\r\nForcing choice with default (\"you pick\"). The skill surfaces its own framework recommendation after the recon search so user can override. Use `scripts/framework_recommender.py` for the heuristic.\r\n\r\nSee [`references/framework_selection.md`](references/framework_selection.md) for PICO / SPIDER / Decomposition canon.\r\n\r\n### Q3 (depends on Q1) — Tentative depth\r\n\r\n> **Tentative depth — pick one. Final confirmation comes after the framework breakdown:**\r\n>\r\n> 1. **Quick scan** (5 searches)\r\n> 2. **Standard review** (10 searches)\r\n> 3. **Deep dive** (20 searches)\r\n>\r\n> *Why I'm asking:* I ask this twice — once now to calibrate the recon search emphasis, once after the framework breakdown to confirm. Tentative answer affects which sub-areas to surface first; final answer drives search budget allocation.\r\n\r\nForcing choice. **Re-asked** at the post-Phase-2 checkpoint after the user has seen the framework breakdown.\r\n\r\n**Stop condition:** 3 questions max before Phase 1. The post-Phase-2 checkpoint is its own grill-me moment (framework table + sub-area-adjustment + depth-reconfirmation).\r\n\r\n## Phase 1: Initial Reconnaissance\r\n\r\n**One broad recon search** to map themes, terminology, methodological distinctions.\r\n\r\n- Run the lane check (Consensus available or not), then:\r\n  - Free lane: `python scripts/free_search.py --query \"<broad version of Q1>\" --source both --max 20` (or the esearch/works URL templates above)\r\n  - **If Consensus is available, additionally** run one broad Consensus search and merge\r\n- Query: broad version of Q1 (terminology variants are okay; first search casts wide)\r\n- Record: `citation_tracker.py --action record_search --session NAME --query \"...\"`\r\n- Record received count: `citation_tracker.py --action record_papers_received --session NAME --count N`\r\n\r\nSynthesize for the checkpoint:\r\n- Themes that surfaced\r\n- Terminology variations (e.g., \"LLM\" vs \"large language model\" vs \"GPT-style model\")\r\n- Methodological distinctions (clinical trials vs benchmark eval vs case study)\r\n- Coverage gaps (sub-questions absent from recon results)\r\n\r\n## Phase 2: Framework Selection + Sub-area Generation\r\n\r\nChoose framework (from Q2 OR override based on recon):\r\n- **PICO** — most clinical questions (~70% default)\r\n- **SPIDER** — social / qualitative\r\n- **Decomposition** — technology focus (Problem / Solution / Evaluation / Limitations)\r\n- **Hybrid** — explicit cross-framework mapping\r\n\r\nGenerate **4-5 sub-area questions** mapped to framework components. Each becomes a targeted Phase 3 search.\r\n\r\n## Checkpoint (grill-me forcing-options moment)\r\n\r\nAfter Phase 2, halt and present:\r\n\r\n### 3-4 sentence recon summary\r\n- What themes surfaced\r\n- Terminology landscape\r\n- Evidence landscape characterization\r\n\r\n### Framework breakdown table\r\n\r\n| Framework Component | How It Maps to This Topic | Proposed Sub-area to Explore |\r\n|---|---|---|\r\n| (Component 1) | ... | Sub-area 1 |\r\n| (Component 2) | ... | Sub-area 2 |\r\n| (Component 3) | ... | Sub-area 3 |\r\n| (Component 4) | ... | Sub-area 4 |\r\n| Cross-cutting theme | ... | Sub-area 5 |\r\n\r\n### Depth re-confirmation (forcing choice)\r\n\r\nSurface the **practical constraint**: search lane in use (free / free+Consensus) + approximate ceiling at ~20 results per query per source.\r\n\r\n- Quick scan (5 searches × ~20 results = ~100 papers max per source)\r\n- Standard review (10 searches × ~20 = ~200 papers per source)\r\n- Deep dive (20 searches × ~20 = ~400 papers per source)\r\n\r\n### Sub-area forcing options\r\n\r\n- \"Looks good — proceed with these sub-areas\"\r\n- \"Adjust: add sub-area on [X]\"\r\n- \"Adjust: remove and replace [Y] with [Z]\"\r\n- \"Restart with different framework\"\r\n\r\n### Why I'm asking (the rationale)\r\n\r\n> A wrong framework or sub-area set wastes the search budget. This is the **last cheap moment** to correct course.\r\n\r\n**Wait for user response before Phase 3.** Refuse to start Phase 3 without explicit user choice.\r\n\r\n## Phase 3: Targeted Searches\r\n\r\nSequential (1 query/sec), budget per depth tier. Every search runs on the free lane (`free_search.py` or the URL templates); **if Consensus is available, additionally** run the same query there and merge. See [`references/search_budget_allocation.md`](references/search_budget_allocation.md) for full canon.\r\n\r\n### Quick scan (5 searches)\r\n- 5 sub-area searches (one per sub-area)\r\n- Skip era-gated + review-specific\r\n\r\n### Standard review (10 searches)\r\n- 5 sub-area searches\r\n- 2 review article searches (top 2 sub-areas): `\"systematic review [topic]\"` / `\"meta-analysis [topic]\"` (OpenAlex: add `&filter=type:review`)\r\n- 2 era-gated searches (most important sub-area): historical (PubMed `&maxdate=2015` / OpenAlex `to_publication_date:2015-12-31`) + recent (PubMed `&mindate=2021` / OpenAlex `from_publication_date:2021-01-01`)\r\n- 1 follow-up on highest-cited paper using its key terms + a from-date after its publication year\r\n\r\n### Deep dive (20 searches)\r\n- 5 sub-area searches\r\n- 5 review article searches (one per sub-area)\r\n- 4 era-gated searches (top 2 sub-areas, old + new each)\r\n- 3 follow-ups on top 3 highest-cited papers\r\n- 3 spare for emerging threads (surprising findings to chase)\r\n\r\nThroughout: 1 q/sec rate limit. Sequential. Confirm response before next call. Record each via `citation_tracker.py`.\r\n\r\n## Cross-Search Intelligence\r\n\r\nThree trackers across ALL search results — run `scripts/cross_search_aggregator.py --session NAME` after Phase 3 completes:\r\n\r\n1. **Repeat-hit papers** — same paper appearing in 3+ sub-area searches = likely foundational\r\n2. **Recurring authors** — same author in multiple searches = dominant research group; top 3-5 most frequent matter\r\n3. **Citation-per-year heuristic** — a 2023 paper with 150 citations >> 2008 paper with 150 citations. Use OpenAlex `cited_by_count` for seminal-work identification.\r\n\r\nThese feed the \"Start Here\" + \"Key Research Groups\" + \"Bibliography\" DOCX sections.\r\n\r\n## Phase 4: DOCX Research Guide\r\n\r\nGenerate via Node.js + `docx` library. 8 sections (see [`references/docx_8_sections.md`](references/docx_8_sections.md) for full spec):\r\n\r\n1. **Topic Overview** — single tight paragraph (4-6 sentences)\r\n2. **Start Here — Priority Reading Order** — 5-7 papers ordered: best recent review → foundational → 2-3 frontier → gap/controversy. Each: hyperlinked title + authors/year + 1-sentence contribution + 1-sentence \"what to look for\"\r\n3. **How the Field Got Here** — chronological narrative (1-2 paragraphs) + timeline table (5-8 milestones: Year / Milestone / Significance) + terminology evolution note\r\n4. **Sub-area Guides** (one per sub-area, 4 parts each)\r\n   - 4a. What the Research Shows (2-3 sentence synthesis with inline citations)\r\n   - 4b. Key Papers (3-5 hyperlinked papers with citation count, year, 1-sentence importance)\r\n   - 4c. Key Search Terms (6-10 keywords, synonyms, MeSH, historical terms)\r\n   - 4d. Boolean Search Strings (2-3 ready-to-paste strings)\r\n5. **Key Research Groups** — top 3-5 authors/groups with affiliations, sub-area coverage, representative paper link (from cross-search aggregator)\r\n6. **Open Questions & Gaps** — three categories: methodological / population-context / conceptual-theoretical. Each gap explains *why it matters*.\r\n7. **Bibliography** — alphabetical by first author. Every entry has a clickable link: PubMed URL or DOI (free lane) / \"View on Consensus\" (Consensus-sourced). Every inline citation matches a bibliography entry.\r\n8. **Audit Log** — search summary table (#, query, filters, papers returned, status), counts block, coverage notes including which search lane was used (free / free+Consensus)\r\n\r\n### DOCX Technical Requirements\r\n\r\nDocument the key `docx` library patterns:\r\n\r\n- Page: US Letter, 1-inch margins\r\n- Lists: `LevelFormat.BULLET` (never unicode bullets)\r\n- Hyperlinks: `ExternalHyperlink` with `style: \"Hyperlink\"`, full URL (never truncated)\r\n- Tables: dual widths (`columnWidths` + cell `width`), `ShadingType.CLEAR`\r\n- Validation step after save (zip-integrity check: `python3 -c \"import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()\" output.docx` — no output = intact — then confirm the required sections are present)\r\n\r\nReference the **docx skill** for setup patterns and best practices.\r\n\r\n## Output\r\n\r\n```\r\nresearch_guide_<topic-slug>_<YYYY-MM-DD>.docx\r\n```\r\n\r\nPlus:\r\n- Chat summary block: \"Saved: <path>. Audit: N searches × M unique papers / K cited. Search lane: <free | free+Consensus>.\"\r\n- Audit log printed inline if user asks for it\r\n\r\n## Tooling\r\n\r\n| Script | Role |\r\n|---|---|\r\n| `scripts/free_search.py` | Free keyless search lane — PubMed E-utilities + OpenAlex via stdlib urllib (`--query`, `--source pubmed|openalex|both`, `--max`, `--json`, `--mailto`; exits 2 with a clear message when offline) |\r\n| `scripts/citation_tracker.py` | JSON-backed three-count audit at `~/.litreview_sessions/<session>.json` |\r\n| `scripts/framework_recommender.py` | Heuristic PICO/SPIDER/Decomposition suggestion from research question |\r\n| `scripts/cross_search_aggregator.py` | Repeat-hits + recurring-authors + citation-per-year ranking after Phase 3 |\r\n\r\n## References\r\n\r\n- [`references/framework_selection.md`](references/framework_selection.md) — PICO / SPIDER / Decomposition canon (7+ sources)\r\n- [`references/search_budget_allocation.md`](references/search_budget_allocation.md) — depth tiers + cross-search intelligence + sequential execution rationale (7+ sources)\r\n- [`references/docx_8_sections.md`](references/docx_8_sections.md) — research guide DOCX spec + technical requirements (7+ sources)\r\n\r\n## Anti-Patterns To Reject\r\n\r\n- Parallelizing search calls (any lane)\r\n- Skipping the interactive checkpoint (running all searches without user confirmation)\r\n- Padding thin results with training knowledge\r\n- Defaulting to non-PICO framework without justification\r\n- Citing papers in chat that didn't come from this session's searches\r\n- Attempting Consensus plan-tier detection (deleted — the only runtime check is \"are the Consensus MCP tools available in this session?\")\r\n- Treating Consensus as required (it's an optional enhancement; the free lane is the default)\r\n- Skipping era-gated searches in standard/deep budgets\r\n- Skipping cross-search intelligence (repeat-hits, recurring authors)\r\n- Truncating source URLs in hyperlinks\r\n\r\n---\r\n\r\n**Version:** 1.1.0\r\n**Source spec:** `megaprompts/09-litreview-megaprompt.md` (maintainer-local draft spec — gitignored, not present in the public repository)\r\n**Build pattern:** Path B (direct conversion). Sibling of `pulse` (research-pack shape). v1.1.0: free keyless APIs (PubMed + OpenAlex) became the default search lane; Consensus demoted to optional enhancement; plan-tier detection deleted per the 2026-06 newgen audit + ClawHub rule #3 (no paid-service dependencies)."
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The litreview/ folder contains
        SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/litreview
  exported_at: "2026-11-03T07:44:28.613Z"