@diottodev/runic 1.0.0 → 1.1.0

package/research/litreview/skills/litreview/references/docx_8_sections.md

@@ -0,0 +1,287 @@
+# DOCX Research Guide — 8 Sections + Technical Requirements
+
+This reference answers exactly one decision: **what are the 8 sections of the litreview research guide, and what does each contain to function as a "launching pad" for a researcher entering an unfamiliar field?**
+
+## The Core Frame
+
+The output is a **launching pad**, not a finished review. Frame each section as: "what would a generous colleague tell you over coffee if they knew the field and you didn't?"
+
+That framing rules out:
+- Exhaustive coverage (a launch pad is finite)
+- Comprehensive synthesis (the user will read the papers)
+- Defensible-publishable form (this is orientation, not submission-ready)
+
+And rules in:
+- Clear ordering (read these papers in this order)
+- Honest gaps (here's what's underdeveloped)
+- Practical entry points (here's how to keep searching)
+
+## Section 1: Topic Overview
+
+**Length:** 4-6 sentences, single tight paragraph.
+
+**Contents:**
+- What the field is (1 sentence)
+- Why it matters (1 sentence)
+- Framework used (PICO / SPIDER / Decomposition / hybrid) (1 sentence)
+- Characterization of the evidence landscape (1-2 sentences)
+- Honest caveat or limitation (1 sentence) — e.g., "mostly Western data" or "RCTs are scarce"
+
+**Tone:** Confident but caveated. A colleague summarizing, not a textbook authority.
+
+## Section 2: Start Here — Priority Reading Order
+
+**Length:** 5-7 papers, ordered.
+
+**Order:**
+1. Best recent review (sets the field context)
+2. Foundational paper(s) — 1-2, ranked by repeat-hits + cited-per-year
+3. Frontier papers — 2-3 (most-recent that surfaced multiple times)
+4. Gap / controversy paper — 1 (surfaces what's contested)
+
+**Per paper:**
+- Hyperlinked title (clickable to Consensus)
+- Authors + year
+- One sentence: contribution
+- One sentence: "what to look for"
+
+**Example entry:**
+> 1. **[A systematic review of LLM clinical reasoning](https://consensus.app/...)** — Singhal et al. 2024 — Most comprehensive synthesis of LLM diagnostic performance through 2023. Look for: section on prompting strategy (the field's main tunable variable).
+
+## Section 3: How the Field Got Here
+
+**Length:** 1-2 paragraphs narrative + timeline table.
+
+**Narrative:** chronological story of the field's evolution. 3-5 sentences. What changed, when, why.
+
+**Timeline table:** 5-8 milestones.
+
+| Year | Milestone | Significance |
+|---|---|---|
+| 2015 | First paper applying X to Y | Established the question |
+| 2018 | Method Z introduced | Made evaluation tractable |
+| 2020 | Large-scale dataset W released | Enabled benchmarking |
+| 2023 | Breakthrough result by Group A | Set current state-of-the-art |
+
+**Terminology evolution note:** "Field used 'X' through 2018; now standardly called 'Y'. Older searches must include the older term."
+
+This section is what makes a literature review for the researcher: the linear story plus the moments of inflection. Build it from era-gated search results.
+
+## Section 4: Sub-area Guides
+
+**Length:** One per sub-area (4-5 total), 4 parts each.
+
+### 4a. What the Research Shows
+
+2-3 sentence synthesis with inline citations.
+
+Example:
+> LLMs achieve 70-85% accuracy on clinical reasoning benchmarks (Singhal et al. 2023, Liévin et al. 2024) but performance degrades sharply on novel case presentations (Toma et al. 2024). The variance across model families and prompting strategies is the field's central open question.
+
+Every fact is hyperlinked. Every inline citation matches a bibliography entry (Section 7).
+
+### 4b. Key Papers
+
+3-5 hyperlinked papers. Per paper:
+- Title (hyperlinked)
+- Citation count + year
+- One-sentence importance
+
+### 4c. Key Search Terms
+
+6-10 keywords for the sub-area:
+- Modern preferred terms
+- Synonyms (especially historical)
+- MeSH headings if applicable
+- Domain-specific terms (e.g., "USMLE-style" for clinical reasoning)
+
+### 4d. Boolean Search Strings
+
+2-3 ready-to-paste strings:
+```
+("clinical reasoning" OR "diagnostic reasoning") AND ("large language model" OR LLM OR GPT) AND (evaluation OR benchmark)
+```
+
+User pastes into Consensus / PubMed / Scopus to continue searching beyond what the skill ran.
+
+## Section 5: Key Research Groups
+
+**Length:** 3-5 groups.
+
+**Source:** `scripts/cross_search_aggregator.py` recurring-authors output.
+
+**Per group:**
+- Lead author (or 2-3 authors if collaborative)
+- Affiliation (institution)
+- Sub-areas they cover (from cross-search analysis)
+- Representative paper (hyperlinked, with year)
+- Why they matter (1 sentence)
+
+**Example:**
+> **Singhal, K. et al. (Google DeepMind / Med-PaLM)** — Coverage: clinical reasoning, multimodal medical AI. Representative: ["Towards Generalist Biomedical AI" (2023)](https://...). Why they matter: built the Med-PaLM line; their benchmark methodology defines current state-of-the-art evaluation.
+
+## Section 6: Open Questions & Gaps
+
+**Length:** 3 categories, each with 1-3 gaps.
+
+**Categories:**
+
+1. **Methodological gaps** — what's hard to measure, what we don't have good methods for
+2. **Population / context gaps** — who isn't being studied, where the data isn't
+3. **Conceptual / theoretical gaps** — what we don't understand about the underlying mechanism
+
+**Per gap:**
+- One sentence stating the gap
+- One sentence on *why it matters* — what's downstream of this gap being filled
+
+Example:
+> **Methodological gap:** No standardized benchmark for novel-case clinical reasoning (only retrospective USMLE-style). *Why it matters:* current "85% accuracy" claims may not generalize to real practice where novel cases dominate.
+
+The "why it matters" sentence is what distinguishes a gap list from a complaint list.
+
+## Section 7: Bibliography
+
+**Length:** All cited papers, alphabetical by first author.
+
+**Per entry:**
+- Full citation (author list, title, journal, year, volume/issue, pages)
+- Hyperlinked "View on Consensus" link (full URL, never truncated)
+- Inline-citation key matching Section 4 references (e.g., "Singhal et al. 2024")
+
+**Discipline:**
+- Every inline citation in Sections 1-6 appears in Bibliography
+- Every Bibliography entry is cited at least once
+- No phantom entries (cited but no bib) or orphan entries (bib but never cited)
+- Consensus URLs preserved in full (never `...` truncation)
+
+## Section 8: Audit Log
+
+**Length:** Search summary table + counts block + coverage notes.
+
+**Search summary table:**
+
+| # | Query | Filters | Results | Status |
+|---|---|---|---|---|
+| 1 | broad recon | none | 10 | OK |
+| 2 | sub-area 1 | year_min: 2018 | 10 | OK |
+| ... | ... | ... | ... | ... |
+| 10 | follow-up on Singhal | year_min: 2024 | 7 | thin |
+
+**Counts block:**
+
+```
+Searches executed: 10
+Unique papers received: 47 (after deduplication)
+Papers cited in this guide: 22
+Plan tier detected: Free (10/search cap)
+Theoretical ceiling: 100 papers; received 47 unique (typical deduplication)
+```
+
+**Coverage notes:**
+- Which sub-areas surfaced thin results
+- Plan-tier impact on coverage
+- Suggested manual supplementation (PubMed, Scholar, etc.)
+- Era-gated search yields (terminology shifts detected)
+
+The audit log makes the entire review reproducible and falsifiable. A future reader can rerun the searches and check the work.
+
+## DOCX Technical Requirements
+
+Document the key `docx` library patterns (Node.js):
+
+### Page setup
+
+```js
+const page = {
+  size: "LETTER",
+  margins: { top: 1440, right: 1440, bottom: 1440, left: 1440 }, // 1 inch in twips
+};
+```
+
+### Lists (NEVER unicode bullets)
+
+```js
+new Paragraph({
+  children: [new TextRun(text)],
+  numbering: { reference: "default-bullet", level: 0 },
+});
+// Defined in document numbering config with LevelFormat.BULLET
+```
+
+### Hyperlinks (full URL, "Hyperlink" style)
+
+```js
+new ExternalHyperlink({
+  link: "https://consensus.app/full-url-never-truncated/...",
+  children: [new TextRun({ text: paperTitle, style: "Hyperlink" })],
+});
+```
+
+### Tables (dual widths)
+
+```js
+new Table({
+  columnWidths: [3000, 4000, 2000], // EMU
+  rows: rows.map(r => new TableRow({
+    children: r.cells.map(c => new TableCell({
+      width: { size: c.width, type: WidthType.DXA },
+      shading: { type: ShadingType.CLEAR, color: "auto", fill: "auto" },
+      children: [new Paragraph(c.text)],
+    })),
+  })),
+});
+```
+
+### Validation
+
+After save:
+```bash
+python scripts/office/validate.py output.docx
+```
+
+If validation fails: unpack DOCX (it's a ZIP), fix the offending XML, repack.
+
+Reference the **docx skill** (`docx/SKILL.md` in this repo if installed) for full setup patterns.
+
+## Anti-Patterns
+
+- **Truncating Consensus URLs in hyperlinks** — breaks reproducibility
+- **Phantom bibliography entries** — cited paper missing from bib
+- **Generic "Future Work" section** — Section 6 must be *specific* gaps, not "more research is needed"
+- **No timeline table in Section 3** — narrative-only loses the milestone structure
+- **Unicode bullets (• ‣ ▶)** instead of `LevelFormat.BULLET` — breaks DOCX list rendering in some viewers
+- **Single-width tables** (only `columnWidths` or only cell `width`) — renders inconsistently across Word / LibreOffice / Google Docs
+- **Skipping validation step** — invalid DOCX silently fails to open or renders broken
+- **Audit log without theoretical ceiling** — user can't calibrate "is this comprehensive?"
+
+## Operational Checklist
+
+- [ ] All 8 sections present in DOCX
+- [ ] Section 1: 4-6 sentence paragraph
+- [ ] Section 2: 5-7 papers in priority order
+- [ ] Section 3: narrative + timeline table + terminology note
+- [ ] Section 4: one sub-section per sub-area, 4 parts each
+- [ ] Section 5: 3-5 groups from cross-search aggregator
+- [ ] Section 6: 3 categories with "why it matters" per gap
+- [ ] Section 7: alphabetical, hyperlinked, no phantoms / orphans
+- [ ] Section 8: search table + counts + tier + coverage notes
+- [ ] All Consensus URLs full (no truncation)
+- [ ] `LevelFormat.BULLET` for lists (no unicode bullets)
+- [ ] Tables have both `columnWidths` AND cell `width`
+- [ ] `python scripts/office/validate.py output.docx` PASSes
+
+## Citations (7 sources)
+
+1. **`docx` Node.js library — github.com/dolanmiu/docx (MIT).** Authoritative API source. The technical patterns (Paragraph, ExternalHyperlink, Table, LevelFormat.BULLET) come from its documentation.
+
+2. **OOXML (Office Open XML) Specification — ECMA-376 (4th ed., 2016).** The underlying XML schema for DOCX. Source for the dual-width table pattern (DOCX renderers respect both column widths and cell widths; missing either causes layout inconsistencies).
+
+3. **PRISMA 2020 Statement — Page, M. J. et al., *BMJ* 372, 2021.** Source for the audit-log section requirements (every reported search must include query, filters, results count, status). PRISMA is the international standard for systematic-review reporting.
+
+4. **Cochrane Handbook — Higgins, J. P. T. et al. (Wiley, 2019).** Chapter 4 + Chapter 7 on data extraction and synthesis. Source for the sub-area guide structure (synthesis + key papers + search terms + boolean strings) — Cochrane's standard data-extraction template.
+
+5. **Lipsey, M. W. & Wilson, D. B., *Practical Meta-Analysis* (Sage, 2001).** Source for the bibliography discipline (every inline citation has bib entry; every bib entry is cited). Essential for review integrity.
+
+6. **Tufte, E., *Visual Display of Quantitative Information* (Graphics Press, 1983, 2001 ed.).** Source for the timeline-table pattern (5-8 milestones, not 20+; "milestones" not "events"). Tufte's "small multiples" + "data-ink ratio" principles inform the audit-log table design.
+
+7. **William Strunk Jr. & E. B. White, *The Elements of Style* (Macmillan, multiple eds.).** Source for the "Open Questions & Gaps" voice discipline. Gaps must be specific and consequential, not "more research is needed" filler. Strunk's "omit needless words" applies directly: every gap statement should pass the "why it matters" test.

package/research/litreview/skills/litreview/references/framework_selection.md

@@ -0,0 +1,174 @@
+# Framework Selection — PICO, SPIDER, Decomposition, Hybrid
+
+This reference answers exactly one decision: **which literature-review framework does litreview pick for a given research question, and how does each map sub-areas to search queries?**
+
+Pair with `scripts/framework_recommender.py` for the deterministic heuristic.
+
+## The Core Claim
+
+A literature review's framework determines *what counts as a sub-area*. Pick the wrong framework → sub-areas don't map to actual research → searches return tangential papers → review is shallow.
+
+The three primary frameworks plus hybrid:
+
+| Framework | Best for | Components |
+|---|---|---|
+| **PICO** | ~70% of clinical questions; quantitative outcomes | Population / Intervention / Comparison / Outcome |
+| **SPIDER** | Social / qualitative; experiential questions | Sample / Phenomenon / Design / Evaluation / Research-type |
+| **Decomposition** | Technology-focused; design / engineering | Problem / Solution / Evaluation / Limitations |
+| **Hybrid** | Cross-cutting topics (clinical + tech, etc.) | Pick components from multiple frameworks |
+
+## PICO (default)
+
+Most clinical and biomedical research questions map cleanly to PICO. Example:
+
+> "How do LLMs perform on clinical reasoning tasks compared to physicians?"
+
+| Component | Mapped to topic |
+|---|---|
+| **P**opulation | Clinical reasoning tasks (USMLE, MedQA, NEJM cases) |
+| **I**ntervention | LLM-based reasoning (GPT-4, Claude, Med-PaLM) |
+| **C**omparison | Physician baseline (specialists, residents, generalists) |
+| **O**utcome | Diagnostic accuracy, reasoning quality, time-to-decision |
+
+Each component becomes one or more sub-area searches.
+
+**PICO weaknesses:**
+- Maps poorly to qualitative research (no clear comparison)
+- Maps poorly to technology evaluation (Population is fuzzy)
+- Maps poorly to pure-theory questions (no Intervention)
+
+When PICO doesn't fit cleanly → SPIDER or Decomposition.
+
+## SPIDER (social / qualitative)
+
+Designed for qualitative + mixed-methods research where PICO breaks. Example:
+
+> "How do clinicians experience burnout in academic medicine?"
+
+| Component | Mapped to topic |
+|---|---|
+| **S**ample | Clinicians in academic medical centers |
+| **P**henomenon | Burnout (specifically: emotional exhaustion, depersonalization, reduced accomplishment) |
+| **D**esign | Qualitative interviews, ethnography, phenomenology |
+| **E**valuation | Lived experience, narrative themes |
+| **R**esearch-type | Qualitative, mixed-methods |
+
+Strong signal for SPIDER:
+- Question contains "experience", "perception", "meaning", "lived"
+- Outcome is hard to quantify
+- Research methods involve interviews or observation
+
+## Decomposition (technology / engineering)
+
+Designed for design / build / evaluate questions. Example:
+
+> "How are retrieval-augmented generation systems evaluated for clinical Q&A?"
+
+| Component | Mapped to topic |
+|---|---|
+| **P**roblem | Clinical Q&A: high recall, factual accuracy, citation traceability |
+| **S**olution | RAG architecture (retriever + generator combinations) |
+| **E**valuation | Benchmarks (MMLU-clinical, MedMCQA, custom Q&A sets) |
+| **L**imitations | Hallucination rates, latency, retrieval quality |
+
+Strong signal for Decomposition:
+- Question is about a *system* or *method*, not a population
+- Question implicitly has "Problem → proposed Solution → how to test → known issues" structure
+- Common in CS / ML / engineering research
+
+## Hybrid (cross-cutting)
+
+When no single framework fits, mix components. Example:
+
+> "How effective is AI-assisted radiology workflow integration in community hospitals?"
+
+| Component | Source framework | Mapping |
+|---|---|---|
+| Population | PICO | Community hospital radiology departments |
+| Intervention | PICO | AI-assisted workflow integration (tool: vendor X) |
+| Phenomenon | SPIDER | Workflow change, radiologist experience |
+| Outcome | PICO | Read times, diagnostic accuracy, satisfaction |
+| Limitations | Decomposition | Integration friction, false-positive rate |
+
+Hybrid framing is more work but more accurate for questions that genuinely span disciplines.
+
+## The Framework Recommender Heuristic
+
+`scripts/framework_recommender.py` uses keyword signals to suggest a framework:
+
+| Signal in research question | Suggests |
+|---|---|
+| "compared to", "vs", "versus", "better than" | PICO (Comparison) |
+| "intervention", "treatment", "drug", "therapy" | PICO (Intervention) |
+| "experience", "perception", "meaning", "narrative" | SPIDER (Phenomenon) |
+| "qualitative", "interview", "ethnography" | SPIDER (Design) |
+| "system", "model", "algorithm", "architecture" | Decomposition (Solution) |
+| "benchmark", "evaluation", "metric" | Decomposition (Evaluation) |
+| Multiple signals across frameworks | Hybrid |
+| No strong signal | PICO (default) |
+
+The recommender outputs:
+- Recommended framework
+- Confidence (high / medium / low)
+- Rationale (which signals fired)
+- 4-5 sub-area starter questions mapped to framework components
+
+The skill then surfaces this in the post-Phase-2 checkpoint for user confirmation/override.
+
+## When the User Says "You Pick"
+
+Q2's "you pick" option triggers the recommender. The skill:
+
+1. Runs Phase 1 recon search (using broad terminology from Q1)
+2. After recon, runs the recommender heuristic against Q1 text
+3. Surfaces in checkpoint: "I'm recommending {framework} because {rationale}. Override if you want."
+
+User can override at checkpoint. Refusing to commit (just saying "go") → use recommender's pick.
+
+## Anti-Patterns
+
+### Defaulting to PICO without justification
+
+PICO works for 70% but fails the other 30%. Defaulting to PICO for a SPIDER question wastes the search budget. The recommender prevents this; manual override should have justification.
+
+### Hybrid for everything
+
+Hybrid framing is more work and produces fuzzier sub-areas. Use only when a single framework genuinely fails. Default to non-hybrid; promote to hybrid only when checkpoint review surfaces real cross-cutting components.
+
+### Forcing the framework to fit
+
+If 3 of 5 components don't map naturally, the framework is wrong. Restart with a different framework rather than papering over the misfit.
+
+### Picking framework before reading Q1
+
+The recommender requires Q1 text. Asking Q2 before Q1 is answered loses signal.
+
+### Ignoring the recommender's recommendation
+
+If the recommender suggests SPIDER with high confidence and the user picks PICO anyway, gently challenge: "I see qualitative signals in your question. Want me to use SPIDER, or do you have a reason to insist on PICO?" Once. Honor user override after one push-back.
+
+## Operational Checklist
+
+- [ ] Q1 answered before Q2 (recommender needs Q1 text)
+- [ ] Q2 forcing choice with "you pick" default
+- [ ] `framework_recommender.py` run after Q1 (cached for checkpoint)
+- [ ] Recommendation surfaced in checkpoint with rationale
+- [ ] User can override at checkpoint
+- [ ] Sub-areas mapped 1-to-1 with framework components
+- [ ] Cross-cutting 5th sub-area added regardless of framework
+
+## Citations (7 sources)
+
+1. **Sackett, D. L. et al., *Evidence-Based Medicine: How to Practice and Teach EBM* (Churchill Livingstone, 1997, multiple eds.).** Origin of PICO as a clinical-question framing tool. The "PICO" acronym dates from this text. https://en.wikipedia.org/wiki/Evidence-based_medicine
+
+2. **Cooke, A., Smith, D., & Booth, A., "Beyond PICO: The SPIDER Tool for Qualitative Evidence Synthesis" — *Qualitative Health Research* 22(10), 2012, pp. 1435-1443.** Origin of SPIDER as a PICO alternative for qualitative research. Documents the systematic failures of PICO on qualitative questions that motivated SPIDER's design.
+
+3. **Booth, A., "Searching for qualitative research for inclusion in systematic reviews: a structured methodological review" — *Systematic Reviews* 5, 2016.** Comparative analysis of PICO vs SPIDER for qualitative work. Source for the "SPIDER for social/qualitative" guidance.
+
+4. **PRISMA 2020 Statement — Page, M. J. et al., *BMJ* 372, 2021.** The systematic-review reporting standard. Section on "Eligibility criteria" formalizes the framework-driven approach to defining inclusion/exclusion criteria from sub-areas.
+
+5. **Cochrane Handbook for Systematic Reviews of Interventions — Higgins, J. P. T. et al. (Wiley, 2019, online updates).** Authoritative source for PICO-driven systematic review methodology. Chapter 4 on "Searching for and selecting studies" formalizes the framework → sub-area → search-string mapping pattern.
+
+6. **Hewitt-Taylor, J., "Use of constant comparative analysis in qualitative research" — *Nursing Standard* 15(42), 2001.** Source for the cross-cutting-theme pattern that litreview adds as a 5th sub-area regardless of framework. Constant comparative analysis surfaces themes that cross conventional framework boundaries.
+
+7. **JBI Evidence Synthesis methodology — Joanna Briggs Institute manual (jbi.global).** Comprehensive framework comparison: PICO for quantitative effectiveness, PICo (lowercase 'o' for context) for qualitative, PEO for risk factors, CoCoPop for prevalence. The litreview skill simplifies to PICO/SPIDER/Decomposition + hybrid but the JBI manual catalogs ~12 framework variants for specialty cases.

package/research/litreview/skills/litreview/references/search_budget_allocation.md

@@ -0,0 +1,200 @@
+# Search Budget Allocation — Quick / Standard / Deep + Cross-Search Intelligence
+
+This reference answers exactly one decision: **how does litreview spend its search budget across the 5/10/20 depth tiers, and what makes the cross-search intelligence layer add value beyond per-query results?**
+
+Pair with `scripts/cross_search_aggregator.py` for the deterministic implementation.
+
+## The Core Constraint
+
+Consensus has a **1 query/second rate limit**. NEVER parallelize. Sequential execution is the only mode that doesn't break the rate limit. This is the same rule pulse uses for Reddit/HN/Web — research-pack convention.
+
+Plus a **plan-tier cap**: free tier returns ~10 results per query; Pro returns ~20. Detected at first search response.
+
+The combination produces hard budget ceilings:
+
+| Tier | Plan | Theoretical max papers |
+|---|---|---|
+| Quick scan (5 q) | Free | 50 |
+| Quick scan (5 q) | Pro | 100 |
+| Standard (10 q) | Free | 100 |
+| Standard (10 q) | Pro | 200 |
+| Deep dive (20 q) | Free | 200 |
+| Deep dive (20 q) | Pro | 400 |
+
+These are *theoretical* — deduplication reduces the actual unique paper count by 30-50% in practice.
+
+## Why Three Tiers (Not One Adaptive Budget)
+
+Adaptive budgeting (run more searches if early results are thin) sounds smart but:
+
+1. **User can't predict run time.** A 5-search budget runs in ~5s; a 20-search adaptive could run 10-30s.
+2. **Sunk-cost bias kicks in.** Once 10 searches run, "let's do 5 more" is hard to resist even if results aren't worth it.
+3. **Cross-search intelligence works best at fixed N.** Repeat-hit and recurring-author signals stabilize at known sample sizes.
+
+Fixed tiers with explicit allocations beat adaptive budgets for research-orientation tasks.
+
+## Quick Scan (5 searches)
+
+Budget allocation:
+- **5 sub-area searches** (one per sub-area from Phase 2)
+- Skip era-gated searches
+- Skip review-specific searches
+- Skip follow-ups
+
+Use when:
+- User wants a fast orientation (~30s with 1 q/sec)
+- Topic is well-known to user; they just need pointers
+- Plan tier is free + topic is reasonably narrow
+
+**Note in audit:** "Quick scan tier — review articles + era-gated comparisons omitted. Bibliography may be thin on foundational older work."
+
+## Standard Review (10 searches)
+
+Budget allocation:
+- **5 sub-area searches** (one per sub-area)
+- **2 review article searches** (top 2 sub-areas):
+  - `"systematic review [topic]"` AND `"meta-analysis [topic]"`
+- **2 era-gated searches** (most important sub-area):
+  - `year_max: 2015` → reveals terminology evolution
+  - `year_min: 2021` → captures current frontier
+- **1 follow-up** on highest-cited paper:
+  - Use its key terms + `year_min: <publication_year + 1>`
+  - Surfaces papers that built on this work
+
+Use when (default tier):
+- User has some familiarity but wants depth
+- Plan tier allows reasonable coverage
+- Time budget is 1-2 minutes total
+
+## Deep Dive (20 searches)
+
+Budget allocation:
+- **5 sub-area searches**
+- **5 review article searches** (one per sub-area)
+- **4 era-gated searches** (top 2 sub-areas, old + new each):
+  - Sub-area A: `year_max: 2015` + `year_min: 2021`
+  - Sub-area B: `year_max: 2015` + `year_min: 2021`
+- **3 follow-ups on top 3 highest-cited papers** (their terms + `year_min`)
+- **3 spare for emerging threads** — surprising findings from earlier searches worth chasing
+
+Use when:
+- Topic is genuinely new to user
+- Comprehensive orientation is the goal
+- Plan tier is Pro (free tier deep-dive is bottlenecked at ~200 papers)
+
+## Cross-Search Intelligence
+
+Three trackers across ALL Phase 3 search results. Run after Phase 3 completes via `scripts/cross_search_aggregator.py --session NAME`.
+
+### Tracker 1: Repeat-Hit Papers (foundational signal)
+
+A paper appearing in **3+ sub-area searches** is signal that it's foundational — multiple sub-fields cite it, suggesting cross-cutting importance.
+
+Use repeat-hits to populate "Start Here" DOCX section:
+- Repeat-hit + high citation → priority foundational paper
+- Repeat-hit + recent → likely emerging classic
+- Repeat-hit but few citations → niche but cross-cutting
+
+### Tracker 2: Recurring Authors (dominant research group signal)
+
+Same author appearing across **multiple sub-area searches** = research group dominant in this area.
+
+Top 3-5 most-frequent authors → "Key Research Groups" DOCX section.
+
+Pattern:
+- 5+ search appearances → dominant group (cite representative paper)
+- 3-4 appearances → significant but not dominant
+- 1-2 appearances → not a "group" signal; may still be high-impact individual
+
+Note: a single highly-cited paper isn't a "group" signal — the recurrence across multiple sub-areas matters.
+
+### Tracker 3: Citation-Per-Year (seminal-work heuristic)
+
+Raw citation count is biased toward older papers (more time to accumulate citations). Citations-per-year normalizes:
+
+- Paper A: 2008, 150 citations → 9.4 cites/year
+- Paper B: 2023, 150 citations → 50 cites/year
+
+Paper B is much more seminal in current discourse despite equal absolute citation count.
+
+Citation-per-year ranking → "Start Here" priority ordering.
+
+## Why Cross-Search Intelligence Matters
+
+Per-query results show "papers about this sub-area". Cross-search intelligence shows "patterns across the whole field":
+
+- Repeat-hits reveal foundational structure
+- Recurring authors reveal who's doing the work
+- Citation-per-year reveals what's currently shaping discourse
+
+A literature review WITHOUT cross-search intelligence is just a list of papers. WITH it, the review surfaces the *structure* of the field.
+
+## Sequential Execution Discipline
+
+Each Consensus call must wait for the prior response. NEVER parallelize:
+
+```
+search_1 → wait response → record → 1 second pause → search_2 → ...
+```
+
+If parallel: rate limit triggers 429, error counter increments, after 3 consecutive failures → stop.
+
+`scripts/citation_tracker.py --action record_search` enforces the timestamp gap (rejects calls within 1s of prior).
+
+## Plan-Tier Detection
+
+After search 1, parse the response:
+
+| Signal | Tier |
+|---|---|
+| "Showing top 10" / "upgrade for more" | Free (10/search cap) |
+| 20 papers returned | Pro (20/search cap) |
+| Auth-failure response | API key missing or invalid |
+
+Surface tier at checkpoint:
+
+> Detected free tier (~10 results per search). Calibrating budget:
+>   Quick scan: 5 × 10 = ~50 papers
+>   Standard: 10 × 10 = ~100 papers
+>   Deep dive: 20 × 10 = ~200 papers
+> If you want deeper coverage, Consensus Pro unlocks 20/search.
+
+User chooses depth after seeing the constraint.
+
+## Anti-Patterns
+
+- **Parallelizing searches** — triggers rate limit; data loss
+- **Adaptive "just one more" extensions** — bias-prone; commit to tier upfront
+- **Skipping era-gated searches in standard/deep tiers** — misses terminology shifts
+- **Skipping cross-search aggregation** — reduces review to a paper list
+- **Hardcoding plan tier** — detect at runtime; don't assume free/Pro
+- **Reporting raw citation count without per-year** — over-weights older papers
+- **Counting repeat-hits at threshold 2** — too noisy; 3 is the minimum signal
+
+## Operational Checklist
+
+- [ ] Plan tier detected from search 1 response
+- [ ] Theoretical ceiling reported at checkpoint
+- [ ] Search budget allocated per tier (5/10/20)
+- [ ] Era-gated searches included in standard/deep
+- [ ] Follow-ups on highest-cited papers included
+- [ ] 1 second wait between each Consensus call (timestamp-enforced)
+- [ ] All search results passed through `cross_search_aggregator.py` after Phase 3
+- [ ] Repeat-hit threshold = 3 sub-areas (not 2)
+- [ ] Citation-per-year computed (not raw citation count)
+
+## Citations (7 sources)
+
+1. **Consensus.app documentation — consensus.app/help.** Authoritative source for plan-tier caps (free: 10/search, Pro: 20/search) and 1 q/sec rate limit. The skill detects from response rather than hardcoding because documented values evolve.
+
+2. **Higgins, J. P. T. & Green, S. (eds.), *Cochrane Handbook for Systematic Reviews of Interventions* (Wiley, 2019).** Chapter 4 on search strategy. Source for the era-gated + review-specific + follow-up search categories. The 5/10/20 tier structure is litreview's compression of Cochrane's exhaustive-search methodology.
+
+3. **Greenhalgh, T. & Peacock, R., "Effectiveness and efficiency of search methods in systematic reviews" — *BMJ* 331, 2005, pp. 1064-1065.** Empirical analysis of how many searches are "enough" to surface foundational papers. Source for the diminishing-returns curve that justifies fixed-tier budgets vs adaptive.
+
+4. **Page, M. J. et al., *PRISMA 2020 Statement* — *BMJ* 372, 2021.** Reporting standard for search audit logs. Source for the audit-log DOCX section's required content (search #, query, filters, results returned).
+
+5. **Sandelowski, M. & Barroso, J., *Handbook for Synthesizing Qualitative Research* (Springer, 2007).** Source for cross-search intelligence patterns in qualitative reviews — repeat-hits and recurring-authors are documented signals in narrative synthesis literature.
+
+6. **Lawani, S. M., "Bibliometrics: Its theoretical foundations, methods and applications" — *Libri* 31, 1981.** Foundational bibliometrics paper. Source for the citations-per-year normalization (Lawani's Garfield-style impact normalization). The skill's citation-per-year heuristic is the simplest form of bibliometric normalization.
+
+7. **AWS Architecture Blog — Mike Cohen, "Exponential Backoff and Jitter" (2015) + Marc Brooker, "Timeouts, retries, and backoff with jitter" (Builders' Library, 2019).** Source for the retry-once-after-3s pattern (research-pack convention). Justifies aggressive failure-detection (3 consecutive → stop) over deep retry loops for research workflows.