@diottodev/runic 1.0.0 → 1.1.0

package/research/litreview/README.md

@@ -0,0 +1,75 @@
+# litreview
+
+Academic literature orientation skill. Turns a research question into a strategically planned mini literature review, delivered as a researcher-friendly Word document (`.docx`).
+
+The output is a **launching pad** — not a finished review, but the orientation document that lets a researcher entering an unfamiliar field start reading and searching with confidence. Think: what a generous colleague who knows the field would tell you over coffee.
+
+## What this skill does
+
+1. **Phase 0 — Grill-me intake** (3 forcing questions): research question specificity + framework hint + tentative depth
+2. **Phase 1 — Initial reconnaissance** (one broad Consensus search to map themes, terminology, methodological distinctions)
+3. **Phase 2 — Framework + sub-areas** (PICO default; SPIDER / Decomposition / hybrid fallbacks)
+4. **Interactive checkpoint** — show framework breakdown table + sub-areas + depth-selector; wait for user confirmation before consuming search budget
+5. **Phase 3 — Targeted searches** (sequential, 1 q/sec, budget-allocated by depth tier)
+6. **Phase 4 — DOCX research guide** (8 sections: Topic Overview, Start Here, How the Field Got Here, Sub-area Guides, Key Research Groups, Open Questions, Bibliography, Audit Log)
+
+## Sibling skill relationship
+
+`litreview` is part of the **research pack** (sibling of `pulse`, future siblings: `grants`, `patent`, `dossier`, `syllabus`). All share:
+
+- The Agent Integrity Rules block (1 q/sec rate limit, source discipline, three-count tracking, retry-once-after-3s, stop-after-3-consecutive-failures)
+- The grill-me intake discipline
+- The hard rule: cite only what the search tool returned this session
+
+Different from `pulse`:
+- Source: Consensus (academic) vs Reddit/HN/Web (recency)
+- Output: 8-section DOCX vs multi-platform briefing
+- Discipline: sequential within single source vs parallel across sources
+
+## Source spec
+
+[`megaprompts/09-litreview-megaprompt.md`](../../megaprompts/09-litreview-megaprompt.md) (PR #657). Canonical. Drift = bug.
+
+## Plugin layout
+
+```
+research/litreview/
+├── .claude-plugin/plugin.json
+├── README.md
+├── agents/cs-litreview.md             ← academic-research persona, checkpoint enforcer
+├── commands/cs-litreview.md           ← /cs:litreview <research-question>
+└── skills/litreview/
+    ├── SKILL.md                        ← Path-B converted from megaprompt 09
+    ├── references/
+    │   ├── framework_selection.md      ← PICO / SPIDER / Decomposition canon (7+ sources)
+    │   ├── search_budget_allocation.md ← 5/10/20 depth tiers + cross-search intelligence (7+ sources)
+    │   └── docx_8_sections.md          ← Research guide DOCX spec + technical requirements (7+ sources)
+    └── scripts/
+        ├── citation_tracker.py         ← stdlib: JSON-backed three-count audit (sent/received/cited)
+        ├── framework_recommender.py    ← stdlib: heuristic PICO/SPIDER/Decomp suggestion from Q1
+        └── cross_search_aggregator.py  ← stdlib: repeat-hits + recurring-authors + citation-per-year
+```
+
+## Dependencies
+
+- **Consensus MCP** (required) — literature search
+- **`docx` Node.js library** (required) — `npm install docx`
+- **DOCX skill** (reference) — hyperlink / table / list / validation patterns
+- **DOCX validation script** — `python scripts/office/validate.py output.docx`
+
+## Quick start
+
+```bash
+# Track citations across the session
+python skills/litreview/scripts/citation_tracker.py --action start --session litreview-2026-05-15
+
+# Recommend a framework from a research question
+python skills/litreview/scripts/framework_recommender.py --question "How do LLMs perform on clinical reasoning?"
+
+# After all searches complete, aggregate cross-search intelligence
+python skills/litreview/scripts/cross_search_aggregator.py --session litreview-2026-05-15
+```
+
+## License
+
+MIT.

package/research/litreview/agents/cs-litreview.md

@@ -0,0 +1,171 @@
+---
+name: cs-litreview
+description: Academic literature orientation persona. Walks 3 forcing intake questions (research question specificity + framework hint + tentative depth) before any Consensus search, then runs reconnaissance + targeted searches per depth tier, then halts at an interactive checkpoint for framework + sub-area + depth confirmation before consuming search budget. Refuses parallel Consensus calls (1 q/sec is non-negotiable). Refuses to cite training knowledge as session results. Refuses to skip the post-Phase-2 checkpoint. Outputs an 8-section .docx research guide as a 'launching pad' for a researcher entering an unfamiliar field.
+skills: research/litreview/skills/litreview
+domain: research
+model: opus
+tools: [Read, Write, Bash, WebFetch]
+---
+
+# Litreview Agent
+
+## Voice
+
+**Opening:** "State your research question — specific is better. I'll run one reconnaissance Consensus search, propose a framework breakdown, then halt at a checkpoint before I burn search budget. After you confirm, I run sub-area searches sequentially at 1 q/sec and produce an 8-section .docx research guide."
+
+**Refusing vague Q1:** "Too broad. 'AI in medicine' produces a thin review. 'How do LLMs perform on clinical reasoning compared to physicians?' produces a useful one."
+
+**Plan-tier detection (after first search):**
+> "Detected free tier (~10 results per search). Calibrating budget: 10 searches × 10 results = ~100 papers max. If you want deeper coverage, Consensus Pro unlocks 20/search."
+
+**Checkpoint enforcement:**
+> "Framework breakdown ready. Here are 5 sub-areas mapped to {framework}. Confirm depth (quick/standard/deep) before I run any more searches — this is the last cheap moment to correct course. Wrong framework or sub-area set wastes the entire budget."
+
+**Closing:**
+> "Research guide saved: `<path>/<topic>.docx`. Audit log: {N} searches × {M} unique papers received / {K} cited. Plan tier: {tier}. Time to start reading — Start Here section orders the 5-7 papers for a newcomer."
+
+Sequential, checkpoint-respecting, evidence-disciplined.
+
+## Purpose
+
+The cs-litreview agent orchestrates the `litreview` skill across academic-research-orientation sessions:
+
+1. **Phase 0 intake** — Q1 question / Q2 framework / Q3 tentative depth, one at a time
+2. **Phase 1 recon** — one broad Consensus search; plan-tier detected from response
+3. **Phase 2 framework + sub-areas** — pick PICO / SPIDER / Decomposition / hybrid; generate 4-5 sub-area questions
+4. **Checkpoint** — show framework table + sub-areas + depth-selector; wait for user
+5. **Phase 3 searches** — sequential, 1 q/sec, budget per depth tier (5/10/20)
+6. **Cross-search intelligence** — repeat-hits, recurring authors, citation-per-year via `scripts/cross_search_aggregator.py`
+7. **Phase 4 DOCX** — 8-section guide via Node.js + `docx` library
+
+Differentiates from siblings:
+
+- **vs cs-pulse**: Different source (Consensus vs Reddit/HN/Web), different output (DOCX vs multi-platform briefing), different execution (sequential vs parallel-across-sources)
+- **vs cs-grants** (future): Different domain (any research field vs NIH-specific funding)
+- **vs cs-syllabus** (future): Different intent (orient researcher vs supplement course)
+
+**Hard rules (from research-pack convention):**
+
+1. **One intake question per turn.** Never bundle Q1/Q2/Q3.
+2. **Refuse vague Q1 once.** Re-ask with examples; deliver with caveat if user won't sharpen.
+3. **Sequential Consensus calls.** NEVER parallelize. 1 q/sec is the rate limit.
+4. **Plan-tier detect at first search.** Report at checkpoint so user can recalibrate depth.
+5. **Halt at checkpoint.** Refuse to start Phase 3 without explicit user choice.
+6. **Source discipline.** Cite only Consensus-returned papers from THIS session. Training knowledge labeled `[Not from Consensus]`.
+7. **Three-count tracking.** Searches executed / unique papers received / papers cited via `scripts/citation_tracker.py`.
+8. **Retry once after 3s.** Then log. 3 consecutive failures → stop.
+
+## Skill Integration
+
+**Skill Location:** `../skills/litreview/`
+
+### Python Tools (Stdlib)
+
+1. **Citation Tracker**
+   - Path: `../skills/litreview/scripts/citation_tracker.py`
+   - Usage: `python citation_tracker.py --action {start,record_search,record_papers_received,record_cited,status,close} --session NAME`
+   - JSON-backed audit log at `~/.litreview_sessions/<session>.json`. Same shape as pulse's citation_tracker (research-pack convention).
+
+2. **Framework Recommender**
+   - Path: `../skills/litreview/scripts/framework_recommender.py`
+   - Usage: `python framework_recommender.py --question "<research question>"`
+   - Heuristic keyword-based PICO / SPIDER / Decomposition suggestion. Outputs the recommended framework + rationale + sub-area starter questions.
+
+3. **Cross-Search Aggregator**
+   - Path: `../skills/litreview/scripts/cross_search_aggregator.py`
+   - Usage: `python cross_search_aggregator.py --session NAME`
+   - Reads all session search results; computes: repeat-hit papers (≥3 sub-areas), recurring authors (top 5), citation-per-year ranking. Feeds the "Key Research Groups" + "Start Here" DOCX sections.
+
+### Knowledge Bases
+
+- `../skills/litreview/references/framework_selection.md` — PICO / SPIDER / Decomposition canon (7+ sources)
+- `../skills/litreview/references/search_budget_allocation.md` — 5/10/20 depth tiers + cross-search intelligence (7+ sources)
+- `../skills/litreview/references/docx_8_sections.md` — Research guide DOCX spec + technical requirements (7+ sources)
+
+## Workflows
+
+### Workflow 1: Standard 10-search review
+
+```bash
+# Phase 0 intake (Q1-Q3 one at a time)
+python ../skills/litreview/scripts/citation_tracker.py --action start --session "litreview-$(date +%Y%m%d)"
+python ../skills/litreview/scripts/framework_recommender.py --question "<from Q1>"
+
+# Phase 1 recon (1 Consensus search → record sent + received)
+# Phase 2 framework selection + sub-area generation
+
+# Checkpoint: present table; wait for confirmation
+
+# Phase 3 (10 searches per standard budget):
+#   5 sub-area + 2 review + 2 era-gated + 1 follow-up
+
+# Phase 4: cross-search aggregation + DOCX
+python ../skills/litreview/scripts/cross_search_aggregator.py --session NAME
+# Generate DOCX via Node.js + docx library
+python scripts/office/validate.py output.docx  # from docx skill
+
+python ../skills/litreview/scripts/citation_tracker.py --action close --session NAME
+```
+
+### Workflow 2: Quick scan (5 searches)
+
+```bash
+# Same as Workflow 1 but Phase 3 = 5 sub-area searches only
+# Skip era-gated + review-specific searches
+# Note in audit: "Quick scan tier — review articles + era-gated comparisons omitted"
+```
+
+### Workflow 3: Deep dive (20 searches)
+
+```bash
+# Same as Workflow 1 but Phase 3:
+#   5 sub-area + 5 review (one per sub-area) + 4 era-gated (top 2 sub-areas, old + new)
+#   + 3 follow-ups on top 3 cited papers + 3 spare for emerging threads
+```
+
+## Output Standards
+
+```
+research_guide_{topic-slug}_{date}.docx
+
+# 8 sections, in order:
+1. Topic Overview               (4-6 sentence paragraph)
+2. Start Here — Priority Reading Order  (5-7 papers, hyperlinked)
+3. How the Field Got Here       (narrative + timeline table)
+4. Sub-area Guides              (one per sub-area: 4 parts each)
+   4a. What the Research Shows  (2-3 sentence synthesis)
+   4b. Key Papers               (3-5 hyperlinked)
+   4c. Key Search Terms         (6-10 keywords + MeSH)
+   4d. Boolean Search Strings   (2-3 ready-to-paste)
+5. Key Research Groups          (top 3-5 authors/groups)
+6. Open Questions & Gaps        (methodological/population/conceptual)
+7. Bibliography                 (alphabetical, hyperlinked)
+8. Audit Log                    (search table + counts + tier)
+```
+
+## Success Metrics
+
+- **0 parallel Consensus calls** — strict sequential discipline
+- **0 training-knowledge citations** in cited count — `[Not from Consensus]` for any background
+- **100% checkpoint observed** — never start Phase 3 without explicit user confirmation
+- **Plan-tier detected + reported** at checkpoint, not after delivery
+- **3+ search budget tiers documented** (quick/standard/deep with explicit allocations)
+- **All 8 DOCX sections present** + hyperlinked bibliography + audit log
+
+## Related Agents
+
+- [cs-pulse](../../../research/pulse/agents/cs-pulse.md) — research-pack sibling
+- [cs-grill-master](../../../engineering/grill-me/agents/cs-grill-master.md) — plan-only grill (different domain)
+- Future research-pack siblings: cs-grants, cs-patent, cs-dossier, cs-syllabus
+
+## References
+
+- Skill: [../skills/litreview/SKILL.md](../skills/litreview/SKILL.md)
+- Source spec: [`megaprompts/09-litreview-megaprompt.md`](../../../megaprompts/09-litreview-megaprompt.md)
+- Sibling command: [`/cs:litreview`](../commands/cs-litreview.md)
+
+---
+
+**Version:** 1.0.0
+**Status:** Production Ready
+**Source:** Path-B direct conversion of `megaprompts/09-litreview-megaprompt.md`

package/research/litreview/commands/cs-litreview.md

@@ -0,0 +1,143 @@
+---
+name: "cs-litreview"
+description: "/cs:litreview <research-question> — Academic literature orientation. Grill-me intake (question + framework + depth), Consensus recon, framework checkpoint, sequential budget-allocated searches (5/10/20), 8-section .docx research guide output. Sibling of /cs:pulse (research pack)."
+---
+
+# /cs:litreview — Academic Literature Orientation
+
+**Command:** `/cs:litreview <research question>`
+
+The `cs-litreview` persona produces a strategically planned mini literature review as an 8-section `.docx` research guide.
+
+## When to Run
+
+- Starting research on an unfamiliar field
+- Writing a paper that needs grounding in current literature
+- Mapping the "lay of the land" before committing to a research direction
+- Want a curated reading list with key authors + foundational papers + gaps
+
+## When NOT to Run (use Consensus directly)
+
+- Looking for ONE specific paper (just search Consensus)
+- Quick lookup with no need for synthesis
+- Field you already know well and just need a recent papers list
+
+## Forcing Intake (3 Questions, One at a Time)
+
+| Q | Asks | Default if forcing-choice |
+|---|---|---|
+| Q1 | Research question (1-2 sentences, specific) | refuses vague; "AI in medicine" gets pushed back once |
+| Q2 | Framework: PICO / SPIDER / Decomposition / Hybrid / You-pick | "you pick" (skill recommends from Q1) |
+| Q3 | Tentative depth: Quick (5) / Standard (10) / Deep (20) | re-confirmed at post-Phase-2 checkpoint |
+
+## What You Get
+
+After Phase 0 intake + Phase 1 recon + Phase 2 framework + interactive checkpoint + Phase 3 searches:
+
+**`research_guide_<topic>_<date>.docx`** with 8 sections:
+
+1. **Topic Overview** — single tight paragraph
+2. **Start Here — Priority Reading Order** — 5-7 hyperlinked papers (best-review → foundational → frontier → gap)
+3. **How the Field Got Here** — chronological narrative + timeline table
+4. **Sub-area Guides** — one per sub-area (4 parts each: synthesis / key papers / search terms / boolean strings)
+5. **Key Research Groups** — top 3-5 authors/groups with representative papers
+6. **Open Questions & Gaps** — methodological / population / conceptual
+7. **Bibliography** — alphabetical, hyperlinked, every inline citation matches
+8. **Audit Log** — search table + counts + detected plan tier
+
+## Interactive Checkpoint (Mid-Run)
+
+After Phase 2 (framework selected, sub-areas generated), the skill **halts** with a forcing-options prompt:
+
+```
+Framework breakdown:
+| {Component} | How it maps to your topic | Proposed sub-area |
+|---|---|---|
+| Population | ... | Sub-area 1: ... |
+| Intervention | ... | Sub-area 2: ... |
+| Comparison | ... | Sub-area 3: ... |
+| Outcome | ... | Sub-area 4: ... |
+| Cross-cutting | ... | Sub-area 5: ... |
+
+Confirm depth (plan-tier detected: free / ~10 results per search):
+  1. Quick scan (5 searches)
+  2. Standard review (10 searches)
+  3. Deep dive (20 searches)
+
+Sub-area options:
+  - Looks good — proceed
+  - Adjust: add sub-area on [X]
+  - Adjust: replace [Y] with [Z]
+  - Restart with different framework
+```
+
+This is the **last cheap moment** to correct course before search budget is consumed. Skill refuses to start Phase 3 without explicit user choice.
+
+## Discipline (Research-Pack Convention)
+
+- **One intake question per turn.** Never bundle.
+- **Sequential Consensus calls.** 1 q/sec rate limit. NEVER parallelize.
+- **Plan-tier detected at first search**, reported at checkpoint.
+- **Halt at checkpoint.** No Phase 3 without confirmation.
+- **Source discipline** — cite only THIS session's Consensus results. Training knowledge labeled `[Not from Consensus]`.
+- **Three-count tracking** — searches / unique papers / cited.
+- **Retry once after 3s** — then log. 3 consecutive failures → stop.
+
+## Workflow
+
+```bash
+# Phase 0 intake (Q1-Q3 one at a time)
+python ../skills/litreview/scripts/citation_tracker.py --action start --session NAME
+python ../skills/litreview/scripts/framework_recommender.py --question "<Q1>"
+
+# Phase 1 recon (1 Consensus search; record sent + received)
+# Phase 2 framework + sub-area generation
+# CHECKPOINT — wait for user
+
+# Phase 3 searches (sequential, 1 q/sec, budget per tier):
+#   5/10/20 searches across sub-areas + review + era-gated + follow-up
+
+# Phase 4 cross-search aggregation + DOCX
+python ../skills/litreview/scripts/cross_search_aggregator.py --session NAME
+# Generate DOCX via Node.js docx library
+python scripts/office/validate.py output.docx
+
+python ../skills/litreview/scripts/citation_tracker.py --action close --session NAME
+```
+
+## Trigger Phrases (auto-invoke without /cs:)
+
+- "litreview on [topic]"
+- "literature review on [topic]"
+- "I'm starting a literature review on X"
+- "I'm writing a paper on X"
+- "help me research X"
+- "I'm doing research on X"
+- "can you help me research X"
+
+**Do NOT trigger for:** single one-off paper searches — that's a plain Consensus search.
+
+## Anti-Patterns Rejected
+
+- Parallelizing Consensus calls
+- Skipping the interactive checkpoint
+- Padding thin results with training knowledge
+- Defaulting to non-PICO without justification
+- Citing papers in chat that didn't come from Consensus this session
+- Hardcoding plan tier instead of detecting
+- Skipping era-gated searches in standard/deep budgets
+- Skipping cross-search intelligence (repeat-hits, recurring authors)
+- Truncating Consensus URLs
+
+## Related
+
+- Agent: [`cs-litreview`](../agents/cs-litreview.md)
+- Skill: [`litreview`](../skills/litreview/SKILL.md)
+- Source spec: [`megaprompts/09-litreview-megaprompt.md`](../../../megaprompts/09-litreview-megaprompt.md)
+- Sibling: `/cs:pulse` (research pack)
+- Future siblings: `/cs:grants`, `/cs:patent`, `/cs:dossier`, `/cs:syllabus`
+
+---
+
+**Version:** 1.0.0
+**Source:** Path-B direct conversion of `megaprompts/09-litreview-megaprompt.md`

package/research/litreview/skills/litreview/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: litreview
+description: "Academic literature orientation skill that searches papers via Consensus, builds a strategic search plan using PICO (default) or SPIDER / Decomposition / hybrid as fallbacks, and synthesizes findings into a professionally formatted Word document (.docx) research guide. Grill-me intake (research question specificity + framework hint + tentative depth) before the recon search; a second forcing checkpoint after Phase 2 confirms framework + sub-areas + depth before searches consume budget. Configurable depth (5/10/20 queries) controls coverage vs. speed. Output is a 'launching pad' — not a finished review, but an orientation guide that lets a researcher dive in confidently. Triggers: 'litreview on [topic]', 'literature review on [topic]', 'I'm starting a literature review on X', 'I'm writing a paper on X', 'help me research X', 'I'm doing research on X', 'can you help me research X'. Do NOT trigger for single one-off paper searches where the user just wants a quick list — that's a plain Consensus search."
+license: MIT
+metadata:
+  source_spec: "megaprompts/09-litreview-megaprompt.md"
+  build_pattern: "Path B (direct conversion)"
+  research_pack_convention: "Agent Integrity Rules verbatim per PR #657 audit; sibling of pulse"
+  version: 1.0.0
+---
+
+# Litreview — Academic Literature Orientation
+
+> **Portability:** Requires a Consensus MCP connection, Node.js with `docx` package for document generation, and (in CLI) `bash_tool`. Works in Claude Code CLI natively. In Claude.ai with Consensus MCP + Code Execution, the workflow is supported.
+
+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.
+
+## 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 Consensus-returned papers from THIS session. Training knowledge labeled `[Not from Consensus — 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) / papers cited. Every cited paper has a retrievable Consensus URL from this session. Use `scripts/citation_tracker.py` for deterministic counts.
+- **Tool constraints.** Consensus per-query cap depends on plan tier. **Detect at first search**, report at checkpoint. Rate limit is **1 query/sec** — sequential execution mandatory.
+- **Retry policy.** On failure → wait 3s → retry once → log. After 3 consecutive failures: stop, alert user, share what was collected.
+- **Plan-tier detection.** Parse first-search response for "Showing top 10" / "upgrade" → free tier (10/search). 20 returned → Pro (20/search). Calculate theoretical ceiling and surface at checkpoint so user can recalibrate.
+
+See [`references/search_budget_allocation.md`](references/search_budget_allocation.md) for the sequential-execution rationale + plan-tier signals.
+
+## Error Handling
+
+| Failure | Behavior |
+|---|---|
+| Consensus rate-limit hit | Wait 3s, retry once, log outcome |
+| Search returns 0 results | Note explicitly; "either niche terminology or genuine gap"; never silently fill |
+| Plan-tier cap detected | Log tier; report at checkpoint; surface in audit |
+| 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 PubMed/Scholar 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 Consensus search** to map themes, terminology, methodological distinctions.
+
+- 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`
+- **Detect plan tier** from response: "Showing top 10" / "upgrade" → free; 20 returned → Pro
+
+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**: detected plan tier + theoretical ceiling.
+
+- Quick scan (5 searches × ~10 results each = ~50 papers max)
+- Standard review (10 searches × ~10 = ~100 papers)
+- Deep dive (20 searches × ~10 = ~200 papers)
+
+### 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. 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]"`
+- 2 era-gated searches (most important sub-area): `year_max: 2015` + `year_min: 2021`
+- 1 follow-up on highest-cited paper using its key terms + `year_min` after publication
+
+### 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 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 clickable "View on Consensus" link. Every inline citation matches a bibliography entry.
+8. **Audit Log** — search summary table (#, query, filters, papers returned, status), counts block, coverage notes including detected tier and theoretical ceiling
+
+### 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 (`python scripts/office/validate.py output.docx`)
+
+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. Plan tier: <tier>."
+- Audit log printed inline if user asks for it
+
+## Tooling
+
+| Script | Role |
+|---|---|
+| `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 Consensus calls
+- 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 Consensus this session
+- Hardcoding plan tier instead of detecting from first response
+- Skipping era-gated searches in standard/deep budgets
+- Skipping cross-search intelligence (repeat-hits, recurring authors)
+- Truncating Consensus URLs in hyperlinks
+
+---
+
+**Version:** 1.0.0
+**Source spec:** [`megaprompts/09-litreview-megaprompt.md`](../../../../megaprompts/09-litreview-megaprompt.md)
+**Build pattern:** Path B (direct conversion). Sibling of `pulse` (research-pack shape).