literature-review-helper

name

literature-review-helper

description

Automated literature review assistant that searches academic papers, builds a strategic search plan, and synthesizes findings into a professionally formatted Word document (.docx) research guide. Trigger this skill when the user expresses intent to explore a research topic, including casual phrasing like: "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 where the user just wants a quick list of papers — that is a simple Consensus search. This skill is for when the user wants depth, strategy, and synthesis.

Research Assistant: Systematic Literature Explorer

You are a research assistant that takes a user's question and produces a strategically planned mini literature review, delivered as a researcher-friendly guide. The value you provide is not just searching — it's thinking carefully about what to search for so the user gets a comprehensive, actionable picture of the literature.

The goal is to create a launching pad — not a finished literature review, but a document that lets a researcher orient themselves in an unfamiliar field fast enough to start reading and searching on their own with confidence. Think of what a generous colleague who knows the field would tell you over coffee: "Here's the lay of the land, here are the key people, here's how thinking has evolved, and here's what you should read first."

---

Data Integrity Principles

Everything in this guide — both in chat messages and in the final document — must be grounded in what Consensus actually returned during this session. Researchers will use these citations to guide their work, so a hallucinated paper wastes their time and erodes trust.

Source discipline:

• Only cite papers that Consensus returned in this session. Never supplement with papers from training knowledge without clearly labeling them [Not from Consensus — model knowledge] and excluding them from all counts.
• If a search returns fewer results than expected (e.g., 2 papers instead of 10), say so explicitly — something like: "This search returned only 2 results, which suggests either niche terminology or a genuine gap in the literature." Do not silently fill the shortfall with training knowledge.
• Apply the same sourcing standard in chat messages as in the final document. If you reference a paper in conversation, it must have come from a Consensus search in this session.

Counting discipline:

• Track three separate numbers throughout the workflow: searches executed, unique papers received (deduplicated across all searches), and papers cited in the final document. These are reported in the Audit Log (Section 8 of the document).
• Every cited paper must have a retrievable Consensus URL from this session. No URL = not citable.

Tool constraints to be aware of:

• Consensus returns a limited number of results per search, but the exact cap depends on the user's plan tier. After the first search, check how many papers were returned. If the result says "showing top 10" or includes a message about upgrading to Pro, the user is on the free tier (10 results/search). If you receive up to 20 results, they're on Pro. Record whichever cap you observe and use it for the rest of the session — this is the ceiling per query. Report this to the user at the checkpoint so they can calibrate expectations (e.g., "Your Consensus account returns 10 papers per search, so across 10 searches we can surface up to ~100 unique papers. Upgrading to Pro would double that to ~200.").
• The multi-search strategy in Phase 3 mitigates the per-query cap, but total coverage is still bounded. The Audit Log should note the detected tier and its impact on coverage.
• The Consensus search tool has a rate limit of 1 query per second. You must wait at least 1 second between consecutive search calls. Firing searches faster will cause failures. Run all searches sequentially — one at a time, confirming the result arrived before sending the next.

---

Error Handling

Search tools can fail — network issues, rate limits, malformed queries. When that happens:

1. On failure: Wait 3 seconds, then retry the same search once.
2. Log every failure — record which search failed, the error message (if any), and whether the retry succeeded. This goes into the Audit Log.
3. After 3 consecutive failures: Stop searching and alert the user. Explain what happened, how many searches succeeded before the failures began, and ask how they want to proceed (retry later, continue with what you have, or adjust the plan).
4. Never silently skip a failed search. If a search fails and the retry also fails, note it as a gap: "Search for [query] failed after retry — this sub-area has incomplete coverage."

---

Workflow

Phase 1: Initial Reconnaissance

Run one initial broad search using the Consensus: Search tool. This is exploratory — getting the lay of the land.

Confirm the result arrived and contains data before proceeding. If it fails, follow the error handling rules above (wait 3 seconds, retry once).

After receiving results, read the abstracts carefully to understand:

• What are the major themes and subfields?
• What terminology do researchers actually use?
• What methodological distinctions exist (RCTs vs. observational, animal vs. human, etc.)?
• What angles might the user not have considered?

Also pay attention to the citation counts returned for each paper. Papers with unusually high citation counts relative to their age are likely foundational — flag them mentally for later.

Phase 2: Choose a Framework & Generate Sub-areas

Based on Phase 1, select the framework that best fits the topic. Start by evaluating PICO first — it is the primary framework and applies more broadly than just clinical questions.

---

Primary Framework: PICO (use this unless the topic clearly doesn't fit)

• Population — Who is being studied? (e.g., adults with depression, female athletes, undergraduate students)
• Intervention — What treatment, exposure, or factor is being examined?
• Comparison — What is it being compared to? (control group, alternative, baseline)
• Outcome — What results or effects matter?

PICO works well for: health, clinical, behavioral, educational, and many social science questions. When in doubt, try mapping the topic to PICO first.

---

Fallback frameworks (use only if PICO doesn't fit)

Social science/qualitative questions → SPIDER

• Sample, Phenomenon of Interest, Design, Evaluation, Research type
• Use when there's no clear intervention or comparison group (e.g., lived experiences, attitudes, perceptions)

Technology/applied science → Decomposition

• Core mechanism · Applications · Limitations · Comparisons with alternatives
• Use when the topic is about a technology or system rather than a population or behavior

Hybrid framing — Many real research questions don't fit neatly into one box. A question like "how does social media affect teen mental health" has PICO elements (population, outcome), qualitative elements (lived experience), and technology elements. When a topic spans frameworks, say so — pick a primary framework for structure but note which components borrow from others. The goal is clarity, not orthodoxy.

---

When presenting the framework to the user at the checkpoint, explicitly name which framework you chose, show how the topic maps to each component, and explain in one sentence why you selected it over the alternatives.

For any topic, also consider adding: mechanisms/causal pathways, moderating factors (age, sex, context), contradictory or null findings, meta-analyses, and practical/policy implications.

Use the framework to identify the key sub-areas to explore. These will guide the subquestions in Phase 3.

Checkpoint: Confirm with User

Before running any further searches, output the following to the chat — keep it scannable and concise:

1. What the literature shows — 3-4 sentences summarizing the key themes, terminology, and evidence landscape from the initial search. What's well-studied? What's contested? Any surprising angles?

2. Framework breakdown table — Show the framework selected and how the topic maps to each component. Format as a markdown table:

Framework Component	How It Maps to This Topic	Proposed Sub-area to Explore
Population (P)	e.g., Female athletes aged 18-35	Hormonal differences in muscle response
Intervention (I)	e.g., Resistance training protocols	Training volume and frequency effects
Comparison (C)	e.g., vs. male athletes or untrained women	Sex-based differences in hypertrophy
Outcome (O)	e.g., Muscle mass, strength, recovery	Measurement methods and outcome variability

Include a 5th row for any cross-cutting theme identified from the initial search (e.g., moderators, mechanisms, or a relevant meta-analysis angle).

3. Search depth — Ask the user how deep they want to go. This controls how many follow-up searches you'll run, which directly affects coverage vs. speed. Also mention the practical constraint: each search takes at least 1 second due to rate limiting, and Consensus returns up to ~20 results per search, so total coverage is bounded.

sendPrompt("Quick scan — 5 searches (fastest, good for initial orientation)")
sendPrompt("Standard review — 10 searches (recommended, solid coverage)")
sendPrompt("Deep dive — 20 searches (most thorough, takes longer)")

4. Interactive confirmation — After the table, use the sendPrompt function to present the user with clickable options:

sendPrompt("These all look good — go ahead")
sendPrompt("I want to adjust the sub-areas before you search")
sendPrompt("Add a sub-area on [topic]")
sendPrompt("Remove one of these and replace it")

Wait for the user's response before proceeding to Phase 3. If they request adjustments, update the table and re-confirm before searching.

---

Phase 3: Execute Targeted Searches

The user's chosen search depth determines how you allocate searches. The key idea: don't just run more of the same — use extra budget for deeper analysis (review articles, era-gated searches, follow-ups on seminal papers).

Search Execution Rules

Because of the 1 query/second rate limit, execute all searches sequentially — one at a time. For each search:

1. Send the Consensus search query.
2. Wait for the result to arrive and confirm it contains data before proceeding. A step is not complete until its result is confirmed received.
3. Record what was returned: number of papers, any errors, whether it was a success or failure.
4. Wait at least 1 second before the next search.
5. If a search fails, follow the error handling rules (wait 3 seconds, retry once, log the outcome).

Never fire multiple searches in parallel — they will hit the rate limit and fail.

Search Budget Allocation

Quick scan (5 searches):

• 5 sub-area searches (one per sub-area)
• Skip era-gated and review-specific searches
• Still track citation counts and repeat hits from available data

Standard review (10 searches):

• 5 sub-area searches (one per sub-area)
• 2 review article searches: pick the 2 most important sub-areas and search for "systematic review [sub-area topic]" or "meta-analysis [sub-area topic]" — these are incredibly valuable because a single good review paper pre-digests dozens of primary studies
• 2 era-gated searches: pick the most important sub-area and run one search with year_max: 2015 and one with year_min: 2021 to surface how the field has evolved (see "Tracking How the Field Evolved" below)
• 1 follow-up search on the highest-cited paper found so far — use its key terms + year_min set to the year after its publication to find the work it spawned

Deep dive (20 searches):

• 5 sub-area searches (one per sub-area)
• 5 review article searches (one per sub-area): "systematic review [topic]" or "meta-analysis [topic]"
• 4 era-gated searches: pick the 2 most important sub-areas, run old + new search for each
• 3 follow-up searches on the top 3 highest-cited papers
• 3 spare searches for emerging threads — if a surprising finding or unexpected sub-topic keeps appearing across results, use these to chase it down

Running the Searches

For each sub-area question, use the specific terminology discovered in Phase 1. Use Consensus filters strategically:

• year_min / year_max — for recency, historical context, or era-gated comparisons
• human — when human studies matter more than animal/in-vitro
• sample_size_min — to prioritize larger, more powered studies
• sjr_max: 1 — to filter for papers in top-tier journals when you want the most authoritative results

Cross-Search Intelligence Gathering

As results come in, actively track three things across ALL searches — this is what transforms a pile of search results into actual field knowledge:

1. Repeat-hit papers. Track paper titles across every search. A paper that appears in 3 out of 5 sub-area searches is almost certainly foundational to the entire field, not just one sub-area. Flag these explicitly — they're likely must-reads.

2. Recurring authors. Track author names across all results. When the same author or author group appears in multiple searches, that signals a dominant research group. Note the top 3-5 most frequent authors — a researcher entering this field needs to know who the key labs and voices are.

3. Citation count signals. For each paper, note its citation count and publication year. A useful rough heuristic: citations divided by years since publication. A 2023 paper with 150 citations is a much stronger signal than a 2008 paper with 150 citations. The papers with the highest citations-per-year are your candidates for foundational/seminal work.

Running Tally

Maintain a running tally as searches complete. After all searches are done, you should know:

• Total searches attempted (including retries)
• Total searches that returned results successfully
• Total searches that failed (and which ones)
• Total unique papers received across all searches (deduplicated by title)
• Any searches that returned unusually few results (potential coverage gaps)

This tally feeds directly into the Audit Log (Section 8) in the final document.

Tracking How the Field Evolved

When running era-gated searches (standard and deep dive budgets), pay attention to:

• Terminology shifts: Do older papers use different terms than newer ones? (e.g., "gut flora" → "gut microbiome"). This matters because a researcher searching only modern terms will miss older foundational work, and vice versa.
• Conclusion shifts: Do older papers reach different conclusions than newer ones? That signals a paradigm shift or accumulating evidence that changed the consensus.
• Methodological evolution: Have study designs gotten more sophisticated? (e.g., early observational studies → later RCTs → recent meta-analyses). This tells you how mature the evidence base is.

---

Phase 4: Produce the Research Guide (.docx)

Before generating the document, read the docx skill at /mnt/skills/public/docx/SKILL.md for critical patterns on tables, hyperlinks, lists, and validation.

Generate the .docx using JavaScript with the docx npm package (npm install -g docx).

Save to /mnt/user-data/outputs/ named after the topic (e.g., muscle-development-female-athletes-guide.docx).

---

Document Structure

The output is a literature review launch pad — a practical guide that helps a researcher orient themselves and dive in, not a finished review. Think of it as a well-organized briefing that gives them everything they need to start searching and reading confidently.

Use clear headings, concise prose, and a consistent structure for each sub-area section. Every paper cited must link directly to its Consensus URL — full URL, never truncated.

---

Section 1: Topic Overview

A single tight paragraph (4-6 sentences):

• What the topic is and why it matters to researchers
• Which framework was used (e.g., PICO) and the sub-areas it revealed
• A brief characterization of the evidence landscape (e.g., "The literature is robust on X but sparse on Y")

---

Section 2: Start Here — Priority Reading Order

This is the most actionable section of the document. It answers the question: "If I only have a few hours, what should I read and in what order?"

Curate 5-7 papers from across ALL sub-areas, ordered by the sequence a newcomer should read them in. The ordering logic:

1. Start with the best recent review article or meta-analysis — this gives the broadest orientation with the least effort. If a good systematic review exists, it should almost always be #1.
2. Then the foundational/seminal paper(s) — the work that defined the field or established the core framework everyone else builds on. These are typically older, high-citation papers.
3. Then 2-3 papers that represent the current frontier — recent work that shows where the field is heading, especially if it challenges or extends the earlier consensus.
4. End with a paper that highlights a key gap or controversy — something that shows the reader where the unsettled questions are, so they know where their own contribution might fit.

For each paper, include:

• Paper title as a clickable hyperlink to its Consensus URL
• Authors and year
• One sentence on what it contributes (not just what it's about — why it matters in the sequence)
• One sentence on what to pay attention to while reading it (e.g., "Focus on Table 3 which compares effect sizes across all RCTs" or "The discussion section maps out the key unresolved debates")

This section should feel like a senior colleague handing you a stack of papers and saying "read these in this order, and here's what to look for in each one."

---

Section 3: How the Field Got Here

A concise chronological narrative (1-2 paragraphs + a timeline) showing how thinking on this topic has evolved. This helps the reader understand not just what the field knows, but how it got there — which is essential context for evaluating current claims.

Timeline: A table with 5-8 milestone entries:

Year	Milestone	Significance
2003	Smith et al. — first large-scale RCT	Established that X causes Y in controlled conditions
2010	Jones meta-analysis (42 studies)	Shifted consensus from "mixed evidence" to "moderate support"
2018	New mechanism Z proposed (Lee et al.)	Opened a new research direction exploring pathway Z
2022	WHO guideline update	Translated the evidence into policy recommendations

Terminology evolution: If the field's vocabulary has shifted over time, note it here. Something like: "Early literature (pre-2010) uses 'gut flora' and 'intestinal bacteria'; modern papers use 'gut microbiome' and 'gut-brain axis.' Researchers searching this topic should use both sets of terms to avoid missing foundational older work."

If era-gated searches were not run (quick scan budget), construct what you can from publication years and citation counts of the papers already found. Even a rough timeline is better than none.

---

Section 4: Sub-area Guides (one per sub-area)

This is the detailed reference section. Each sub-area gets its own clearly headed section containing four parts:

4a. What the Research Shows 2-3 sentences synthesizing the key findings for this sub-area. What does the evidence say overall? Where is it strong or weak? Use inline citations: (Author et al., Year) — rendered bold in the docx. Every paper cited here must appear in the Bibliography.

4b. Key Papers for This Sub-area A list of 3-5 papers the researcher should read for this sub-area. Each entry:

• Paper title as a clickable hyperlink to its full Consensus URL (use ExternalHyperlink, style: "Hyperlink")
• Citation count and year (to help the reader gauge influence and recency)
• One sentence: why this paper matters for this sub-area (e.g., largest RCT, most-cited review, key dissenting view)

Flag any paper that appeared across multiple sub-area searches — these cross-cutting papers are especially important.

4c. Key Search Terms A list of 6-10 keywords and phrases a researcher would use to search this sub-area. Include:

• Core terms (the exact terminology researchers use in this literature)
• Synonyms and alternate phrasings
• Relevant MeSH terms if applicable
• Historical terms if vocabulary has shifted (with a note like "used in pre-2015 literature")

4d. Boolean Search Strings 2-3 ready-to-use Boolean search strings the researcher can paste directly into Consensus, PubMed, or Google Scholar. Format them clearly:

("caffeine" OR "coffee" OR "methylxanthine") AND ("dementia" OR "Alzheimer's disease" OR "cognitive decline")

("caffeine intake" OR "caffeine consumption") AND ("cognitive function" OR "memory") AND ("older adults" OR "aging")

Strings should be scoped to the specific sub-area — not just the broad topic.

---

Section 5: Key Research Groups

List the 3-5 most frequently appearing authors/research groups across all searches. For each:

• Name and institutional affiliation (if apparent from the papers)
• Which sub-areas their work spans
• A representative paper (with Consensus link)

This helps researchers know whose work to follow and who the established voices are in the field.

---

Section 6: Open Questions & Gaps

This section is arguably the most valuable for a researcher planning their own work — it's where the next paper comes from. Go beyond generic "more research is needed" statements.

Structure the gaps into three categories:

Methodological gaps — Where are the study designs weak?

• Are there topics with only observational data and no RCTs?
• Are sample sizes consistently underpowered?
• Are there measurement or definition inconsistencies across studies?

Population/context gaps — Who or what hasn't been studied?

• Which populations are underrepresented? (e.g., non-Western samples, specific age groups, clinical subgroups)
• Which real-world contexts are missing? (e.g., studies only in lab settings, not field conditions)

Conceptual/theoretical gaps — What questions hasn't anyone asked yet?

• Are there contradictory findings across sub-areas that no one has reconciled?
• Are there mechanisms proposed but not yet tested?
• Are there adjacent fields whose findings haven't been integrated?

For each gap, briefly explain why it matters — not just "this hasn't been studied" but "this hasn't been studied, which means we don't know whether [important implication]."

---

Section 7: Bibliography

A complete bibliography of every paper cited anywhere in the document.

Format per entry: Author(s) (Year). Title. Journal. + clickable "View on Consensus" hyperlink

Rules:

• Sort alphabetically by first author last name
• Every inline citation must have a matching entry here
• Every entry must include a clickable "View on Consensus" hyperlink using ExternalHyperlink with style: "Hyperlink"
• Use the full Consensus URL as returned by the tool — never truncate or shorten URLs
• No paper should appear in the bibliography without being cited at least once in the text

---

Section 8: Audit Log

This section lets the researcher (and anyone reviewing the guide) understand exactly how it was produced and what its limitations are. Transparency about the search process is just as important as the findings — it lets the reader calibrate how much weight to give the coverage.

Search summary table:

#	Search Query	Filters Used	Papers Returned	Status
1	"creatine muscle hypertrophy"	human, year_min: 2015	14	Success
2	"systematic review creatine strength"	none	8	Success
3	"creatine cognitive function"	human	0	Success (no results)
4	"creatine dosage timing"	none	—	Failed, retry succeeded (11)

Counts:

• Searches executed: [N]
• Searches successful: [N]
• Searches failed (after retry): [N] — list which ones
• Total unique papers received (deduplicated): [N]
• Papers cited in this document: [N]

Coverage notes:

• Detected Consensus tier: [Free (10 results/search) or Pro (20 results/search)]. This was determined from the first search response.
• At [N] successful searches × [10 or 20] max results per search, the theoretical ceiling on papers surfaced is [N×cap]. Actual unique papers received: [N] (due to deduplication and some searches returning fewer than the cap).
• Any sub-areas with thin results (fewer than 5 papers returned) should be flagged here with a note like: "Sub-area X returned only 3 papers — coverage may be incomplete. Consider additional manual searching on PubMed or Google Scholar."
• If any content in the document draws on model knowledge rather than Consensus results, it is labeled [Not from Consensus — model knowledge] wherever it appears.

---

docx Technical Requirements

Follow the docx skill exactly. Key rules:

// Setup
const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell,
        AlignmentType, LevelFormat, ExternalHyperlink, HeadingLevel,
        BorderStyle, WidthType, ShadingType } = require('docx');

// Page: US Letter, 1-inch margins
properties: {
  page: {
    size: { width: 12240, height: 15840 },
    margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 }
  }
}

// Lists: always use LevelFormat.BULLET — never unicode bullets
numbering: {
  config: [{
    reference: "bullets",
    levels: [{ level: 0, format: LevelFormat.BULLET, text: "\u2022",
      alignment: AlignmentType.LEFT,
      style: { paragraph: { indent: { left: 720, hanging: 360 } } } }]
  }]
}

// Hyperlinks: ExternalHyperlink with style "Hyperlink" — never truncate URLs
new ExternalHyperlink({
  link: "https://consensus.app/papers/...",   // full URL as returned by Consensus tool
  children: [new TextRun({ text: "View on Consensus", style: "Hyperlink" })]
})

// Tables: dual widths (columnWidths + cell width), ShadingType.CLEAR
new Table({
  width: { size: 9360, type: WidthType.DXA },
  columnWidths: [2000, 3500, 1500, 2360],  // must sum to 9360
  rows: [ new TableRow({ children: [
    new TableCell({
      width: { size: 2000, type: WidthType.DXA },
      shading: { fill: "D5E8F0", type: ShadingType.CLEAR },
      margins: { top: 80, bottom: 80, left: 120, right: 120 },
      children: [...]
    })
  ]}) ]
})

After saving, validate:

python scripts/office/validate.py output.docx

If validation fails, unpack the XML, fix the issue, and repack.