deep-researcher

What this skill does

# Deep Researcher v2.0

Comprehensive research methodology with file-based tracking, parallel execution, and context management for investigations requiring 5+ sources.

**CRITICAL: All medical evidence and citations must come from PubMed MCP. No exceptions.**

---

## Research Modes

**Quick Research** (1-4 sources): Work in-context, no file structure needed.

**Deep Research** (5+ sources): Use file-based tracking below.

---

## Research Sources (STRICT POLICY)

### ALLOWED for Medical Citations

| Source | Tool | Use Case |
|--------|------|----------|
| **PubMed MCP** | `pubmed_search_articles`, `pubmed_fetch_contents`, `pubmed_article_connections` | ALL medical evidence, trials, mechanisms |
| **Official Guidelines** | `web_fetch` to ACC/ESC/ADA/AHA URLs only | Guideline recommendations |
| **AstraDB RAG** | Knowledge pipeline | Textbook references, pre-loaded guidelines |

### NOT ALLOWED for Medical Citations

| Source | Why Excluded | Allowed Use |
|--------|--------------|-------------|
| ~~OpenAlex~~ | Quality variable | **REMOVED** |
| ~~Perplexity~~ | Not peer-reviewed | Trend discovery only, NEVER cite |
| ~~General web search~~ | Unreliable | Topic discovery only, NEVER cite |
| ~~News articles~~ | Not primary evidence | Background context only |

### PubMed Quality Filters

**Prefer (Tier 1):**
- Randomized Controlled Trials (RCTs)
- Meta-analyses and Systematic Reviews
- Guidelines from ACC/ESC/ADA/AHA

**Accept (Tier 2):**
- Large observational studies from Q1 journals
- Cohort studies with >1000 patients
- Registry data from established registries

**Use Cautiously (Tier 3):**
- Case series (only if no better evidence)
- Expert consensus statements
- Narrative reviews (as background, not primary evidence)

**Reject:**
- Case reports (except for rare conditions)
- Letters to editor
- Preprints without peer review
- Animal studies (unless specifically about mechanisms)

---

## Deep Research Workflow

### Progress Tracking

Create this checklist and update after each step:

```
Deep Research Progress:
- [ ] Step 1: Initialize research project
- [ ] Step 2: Define scope and plan
- [ ] Step 3: Execute research threads (parallel when possible)
- [ ] Step 4: Validate and cross-reference
- [ ] Step 5: Synthesize from files
- [ ] Step 6: Generate final report
```

---

## Step 1: Initialize Research Project

For research requiring 5+ sources, create a project structure:

```bash
mkdir -p ~/research_{topic}/sources
mkdir -p ~/research_{topic}/threads
```

**Project Structure:**
```
~/research_{topic}/
├── plan.md              # Research questions, scope, thread assignments
├── progress.md          # Living checklist, updated throughout
├── sources/
│   └── pubmed.md        # PubMed search results and abstracts
├── threads/
│   ├── thread_1.md      # Independent research thread
│   ├── thread_2.md      # Another thread
│   └── ...
├── validation.md        # Cross-reference and credibility check
├── synthesis.md         # Cross-thread analysis
└── report.md            # Final deliverable
```

**Why file-based?** Context windows fill up. Writing findings to files lets you:
- Continue researching without context pressure
- Synthesize from persistent storage, not memory
- Produce larger, more comprehensive reports
- Resume if interrupted

---

## Step 2: Define Scope and Research Plan

Write `plan.md` with:

```markdown
# Research Plan: {Topic}

## Primary Question
[The main thing we're trying to answer]

## Scope
- Include: [what's in scope]
- Exclude: [what's explicitly out]
- Depth: [overview | detailed | exhaustive]
- Deliverable: [report type and length]

## Research Threads

### Thread 1: {Subtopic A}
- Questions to answer: ...
- PubMed search strategy: [MeSH terms, filters]
- Expected study types: RCTs, meta-analyses, etc.
- Can run parallel? Yes/No

### Thread 2: {Subtopic B}
- Questions to answer: ...
- PubMed search strategy: ...
- Can run parallel? Yes/No

[Continue for 2-5 threads]

## Thread Dependencies
- Thread 3 depends on Thread 1 findings
- Threads 1, 2, 4 can run in parallel

## Synthesis Strategy
How will threads combine into final answer?
```

**Planning Guidelines:**
| Research Type | Threads | Pattern |
|--------------|---------|---------|
| Simple fact-finding | 1-2 | Sequential |
| Drug comparison | 1 per drug (max 5) | Parallel |
| Complex investigation | 3-5 thematic | Mixed |
| Literature review | By time period or theme | Sequential |

---

## Step 3: Execute Research Threads

### PubMed Search Strategy

For each thread, use structured PubMed queries:

```python
# Example search for SGLT2 CV outcomes
pubmed_search_articles(
    queryTerm="SGLT2 inhibitor cardiovascular outcomes randomized controlled trial",
    maxResults=20,
    sortBy="relevance"
)

# Then fetch full details for top results
pubmed_fetch_contents(pmids=["PMID1", "PMID2", ...])

# Find related articles for key papers
pubmed_article_connections(
    sourcePmid="key_paper_pmid",
    relationshipType="pubmed_similar_articles"
)
```

### Parallel Execution Pattern

For independent threads, execute PubMed searches in parallel (multiple tool calls in one turn), then write each to its thread file.

**Example: Comparing SGLT2 Inhibitors**
```
Thread 1: Empagliflozin → pubmed_search "empagliflozin cardiovascular RCT" → threads/empagliflozin.md
Thread 2: Dapagliflozin → pubmed_search "dapagliflozin cardiovascular RCT" → threads/dapagliflozin.md
Thread 3: Canagliflozin → pubmed_search "canagliflozin cardiovascular RCT" → threads/canagliflozin.md
```

Execute all three searches, then write findings to respective files.

### Sequential Execution Pattern

For dependent threads, complete each fully before starting the next.

### Thread File Format

Each `threads/thread_N.md` should contain:

```markdown
# Thread: {Subtopic}

## PubMed Searches Executed
1. Query: [exact query] → [N results] → Top PMIDs: [list]
2. Query: [exact query] → [N results] → Top PMIDs: [list]

## Key Findings

### Finding 1: [Title]
- PMID: [number]
- Citation: [Authors, Journal, Year]
- Study type: RCT / Meta-analysis / Cohort / etc.
- Population: [N patients, characteristics]
- Key result: [HR/OR with 95% CI, p-value]
- Quality: High / Medium / Low [+ brief justification]

### Finding 2: [Title]
- PMID: [number]
...

## Contradictions Found
- PMID X says [claim], PMID Y says [different claim]
- Potential explanation: [patient population, endpoints, timing, etc.]

## Gaps Identified
- No RCT data on [specific question]
- Limited evidence in [patient subgroup]

## Thread Summary
[2-3 sentence synthesis of this thread's findings with key PMIDs cited]
```

### Context Offloading

**After every 5-7 tool calls:**
1. Write current findings to appropriate file
2. Update `progress.md` with status
3. Continue with fresh context

**Trigger for offload:**
- Context feeling "full" (responses slowing, losing track)
- Switching between threads
- Before any synthesis step

---

## Step 4: Validate and Cross-Reference

Read all thread files, then create `validation.md`:

```markdown
# Validation Report

## Facts Requiring Cross-Reference
| Claim | Thread Source | PMID | Verification Status | Confidence |
|-------|--------------|------|---------------------|------------|
| SGLT2i reduces HF hospitalization | Thread 1 | 12345678 | Confirmed by PMIDs 23456789, 34567890 | High |
| Benefit extends to HFpEF | Thread 2 | 45678901 | Conflicting: PMID 56789012 shows null | Investigate |

## Contradictions Analysis
### Contradiction 1: [Description]
- Position A: PMID [X], [study name], found [result]
- Position B: PMID [Y], [study name], found [result]
- Resolution: [Population difference / endpoint difference / timing / unresolved]

## Source Quality Assessment
| PMID | Study | Type | N | Quality | Notes |
|------|-------|------|---|---------|-------|
| 12345678 | EMPA-REG | RCT | 7,020 | High | Industry-funded but well-designed |
| 23456789 | Meta-analysis | MA | 45,000 | High | Published in Lancet |

## Valid