literature-review

What this skill does

# Literature Review

Processes user-provided PDFs one at a time using isolated subagents to prevent context overflow, then synthesizes findings and drafts the Introduction section.

## CRITICAL CONSTRAINTS

```
┌────────────────────────────────────────────────────────────────────┐
│  ⛔ ORCHESTRATOR MUST NEVER READ PDF FILES DIRECTLY ⛔             │
│                                                                    │
│  The orchestrator (you, running this skill) may ONLY read:         │
│  - scope.md                                                        │
│  - inventory.md                                                    │
│  - notes/ethics-summary.md                                            │
│  - notes/papers/*.md (the condensed notes, NOT PDFs)               │
│  - notes/bibliography.md                                           │
│  - notes/literature-synthesis.md                                   │
│                                                                    │
│  If you find yourself about to use the Read tool on a .pdf file,   │
│  STOP. Spawn a subagent instead.                                   │
├────────────────────────────────────────────────────────────────────┤
│  ⛔ EACH SUBAGENT PROCESSES EXACTLY ONE PAPER ⛔                   │
│                                                                    │
│  - One Task tool call = One PDF                                    │
│  - Never pass multiple PDFs to a single subagent                   │
│  - Never ask a subagent to "process the remaining papers"          │
│  - Wait for each subagent to complete before spawning the next     │
│                                                                    │
│  WRONG: Task("Process papers/a.pdf, papers/b.pdf, papers/c.pdf")   │
│  RIGHT: Task("Process papers/a.pdf") → wait → Task("Process b.pdf")│
└────────────────────────────────────────────────────────────────────┘
```

## Architecture: Subagent Pattern

Each paper is processed by an isolated subagent to prevent context overflow:

```
┌─────────────────────────────────────────────────────────────────┐
│                    LITERATURE REVIEW WORKFLOW                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [ORCHESTRATOR]                                                 │
│       │                                                         │
│       ├──► Read scope.md (extract research context)             │
│       │                                                         │
│       ├──► List papers/*.pdf                                    │
│       │                                                         │
│       ├──► For each PDF, spawn isolated subagent:               │
│       │         │                                               │
│       │         ├──► [Subagent] Read ONE PDF                    │
│       │         ├──► [Subagent] Generate notes/papers/*.md      │
│       │         └──► [Subagent] Exit (context cleared)          │
│       │                                                         │
│       ├──► Read all notes/papers/*.md (small files)             │
│       │                                                         │
│       ├──► Generate bibliography + synthesis                    │
│       │                                                         │
│       └──► Draft Introduction                                   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

**Why subagents?**
- Each PDF can be 10-50 pages of dense content
- Processing 30 papers in one context overflows limits
- Subagents process one paper, write condensed notes, then exit
- Orchestrator only reads small markdown note files

## Prerequisites

- `scope.md` must exist (from scoping step)
- `notes/ethics-summary.md` may exist (provides study objectives and population context)
- `papers/` folder with PDF files to process
- Create directories: `notes/papers/`, `notes/papers-library/`, `drafts/`

## Workflow Overview

```
[Step 1: Read scope.md for context]
     │
     ▼
[Step 2: Inventory papers/ folder]
     │
     ▼
[Step 3: Process each PDF via subagent] ─── One at a time
     │                                       └── notes/papers/*.md
     ▼
[Step 4: Generate bibliography] ─── From all notes
     │                              └── notes/bibliography.md
     ▼
[Step 5: Synthesize literature] ─── Aggregate findings
     │                              └── notes/literature-synthesis.md
     ▼
[Step 6: Draft Introduction]
     │
     ▼
[Output] ─── drafts/introduction.md
```

---

## Step 1: Read Scope Context

From `scope.md`, extract comprehensive context to pass to each subagent:
- Research question (frames how to evaluate relevance)
- Key findings (what results need literature context)
- Target journal (determines citation depth)
- Hypothesis (what the manuscript argues)
- Population/methods (for identifying comparable studies)

Create a detailed scope summary to pass to each subagent:

```markdown
## Manuscript Context

You are helping write a scientific research manuscript. Your job is to read ONE paper and extract information most relevant to this manuscript.

### Our Research Question
[Full research question from scope.md]

### Our Hypothesis
[What we expect to find / are arguing]

### Our Key Findings
[Summary of main results - what we found]

### Our Methods
[Brief description of study design, population, techniques used]

### Target Journal
[Journal name] - [word limit] words - [citation style]

### What to Look For in This Paper

As you read, focus on extracting:
1. **Background claims** we can cite to establish the problem's importance
2. **Methodological precedents** that justify our approach
3. **Comparable results** we can compare our findings against
4. **Contradictory findings** we need to address in Discussion
5. **Gaps identified** that our study fills
6. **Quotable statements** that frame the field well
```

If `notes/ethics-summary.md` exists, also include:
- Study objectives from ethics document
- Target population details
- Approved procedures

---

## Step 2: Inventory Papers

List all PDFs in the `papers/` folder:

```bash
ls papers/*.pdf
```

Create processing queue:

```markdown
## Papers to Process

| # | Filename | Status |
|---|----------|--------|
| 1 | smith-2023.pdf | Pending |
| 2 | jones-2022.pdf | Pending |
| 3 | wilson-2021.pdf | Pending |
...
```

Copy PDFs to central library:

```bash
mkdir -p notes/papers-library
cp papers/*.pdf notes/papers-library/
```

---

## Step 3: Process Each PDF via Subagent

**CRITICAL: Process ONE paper at a time using the Task tool.**

For each PDF in the queue:

### 3a. Spawn Subagent

Use the Task tool to spawn an isolated subagent.

**IMPORTANT**: Each Task call must specify exactly ONE PDF file. Do not batch.

```
Task(
  subagent_type: "general-purpose",
  prompt: """
  ⛔ YOU ARE PROCESSING EXACTLY ONE PAPER. DO NOT READ ANY OTHER PDFs. ⛔

  ## Your Role

  You are a research assistant helping write a scientific manuscript. Your job is to:
  1. Read ONE paper
  2. Extract information most relevant to our manuscript
  3. Write condensed notes highlighting what's useful for our paper
  4. Exit immediately after

  ## Your ONE Paper

  **PDF to read**: papers/{filename}.pdf
  **Output file**: notes/papers/{filename}.md

  ## Manuscript Context (What We're Writing)

  {scope_summary}

  ## Instructions

  1. Read ONLY the PDF file specified above
  2. Extract citation metadata (authors, title, journal, DOI, PMID)
  3. Summarize the paper's main contribution
  4. **Focus on relevance**: What from this paper helps our manuscript?
     - Background claims we can cite?
     - Methods similar to ours?
     - Results we can compare against?
     - Contradictions we need to address?
     - Quotes that frame the problem well?
  5. **Recommen