---
name: research-synthesis
description: >-
  Combines multiple sources into balanced analysis with consensus,
  disagreement, and confidence levels. Use when researching technologies,
  comparing approaches, or answering complex multi-source questions.
  NOT for single-source summaries or dataset analysis.
allowed-tools: [Read, Grep, Glob, Bash, WebSearch, WebFetch]
---

## Identity & Scope
**Executor:** either | **Model tier:** sonnet
**Scope:** Multi-source research, synthesis, and comparative analysis. Read-only.
**Off-limits:** Making purchasing decisions, publishing findings, presenting inferences as facts.

### Hard Rules
- No credentials in output or git — ever
- No spending money or publishing content without explicit user approval
- No deleting files — archive first, 48hr hold
- Report completion to boss via structured output

## Essential Principles
1. **Synthesize, don't summarize** — Find connections and contradictions between sources. Guards against: list-of-summaries with no analytical value.
2. **Separate facts from opinions** — Label every claim as fact or opinion. Guards against: blog speculation treated as established knowledge.
3. **Report gaps explicitly** — State what sources do NOT cover. Guards against: false completeness hiding unknowns.
4. **Assign confidence levels** — High/Medium/Low per finding based on source quality and agreement. Guards against: treating a blog post like peer-reviewed research.

## When to Use
- "Research X and summarize" or "compare A vs B vs C"
- Technology evaluation (which framework/tool/service to adopt)
- Literature or market review requiring multi-source synthesis
- "What does the evidence say about X?"
- Vendor or methodology due diligence

## When NOT to Use
- Single document summary — answer directly
- Dataset analysis — use `data-analysis` instead
- Competitive product comparison — use `competitive-analysis` instead
- Writing up findings for publication — use `technical-writing` instead

## Rationalizations to Reject
| Shortcut | Why it's wrong |
|----------|----------------|
| "All sources agree, conclusion is certain" | Consensus among biased sources (vendor blogs) is unreliable |
| "Source is from 2024, close enough" | Technology changes fast; flag date and verify landscape |
| "3 sources is enough" | 3 from the same echo chamber isn't breadth; seek diverse types |
| "Skip recommendations" | Research without recommendations forces user to redo synthesis |
| "Disagreement is minor, go with majority" | Minority positions often contain critical nuance |

## Workflow
### Phase 1: Question Definition
**Entry:** User has stated a research question or comparison goal.
**Actions:**
1. Restate question in precise, answerable form.
2. Identify answer type: factual, comparative, evaluative, or predictive.
3. Define scope: what's in, what's out, relevant time range.
4. List sub-questions needed to resolve the main question.
**Exit:** Research question, scope, sub-questions documented.

### Phase 2: Source Collection
**Entry:** Phase 1 complete.
**Actions:**
1. Search for primary sources: official docs, papers, specs.
2. Search for secondary sources: blogs, reviews, forums.
3. Categorize each: type, date, credibility, potential bias.
4. Ensure diversity: at least 2 source types and 3 distinct perspectives.
5. Flag sub-questions with no sources found.
**Exit:** Source list with categorization; gaps identified.

### Phase 3: Analysis & Synthesis
**Entry:** Phase 2 complete.
**Actions:**
1. Extract findings per sub-question from all sources.
2. Identify consensus: where do multiple credible sources agree?
3. Identify disagreement: where do sources conflict and why?
4. Identify gaps: what remains unanswered?
5. Assign confidence (H/M/L) per finding. Write evidence-grounded recommendations.
**Exit:** Synthesized findings with consensus, disagreement, gaps, confidence, recommendations.

### Phase 4: Verification
**Entry:** All prior phases complete.
**Actions:**
1. Verify every finding cites at least one source.
2. Confirm facts and opinions are labeled. Check confidence levels assigned.
3. Validate gaps stated and JSON format correct. No placeholders remain.
**Exit:** All checks pass — report results to boss/user.

## Output Format
```json
{
  "skill": "research-synthesis",
  "status": "completed",
  "worker": "worker-id",
  "summary": "Researched SQLite vs PostgreSQL for embedded analytics — 8 sources, 5 findings",
  "research_question": "SQLite or PostgreSQL for embedded analytics?",
  "sources": [
    {"title": "SQLite When to Use", "url": "sqlite.org/whentouse.html", "type": "primary", "date": "2025", "credibility": "high"},
    {"title": "Postgres vs SQLite benchmarks", "url": "example.com/bench", "type": "secondary", "date": "2026-01", "credibility": "medium"}
  ],
  "findings": [
    {"item": "SQLite handles ~100K rows with sub-ms queries", "severity": "high", "detail": "Consensus across 4 sources. Degrades above 500K for JOIN-heavy queries.", "type": "fact", "confidence": "high"},
    {"item": "PostgreSQL query planner outperforms on complex joins", "severity": "medium", "detail": "2 benchmark studies. Advantage grows with >5 tables.", "type": "fact", "confidence": "medium"}
  ],
  "consensus": ["SQLite simpler to deploy for small-to-medium datasets"],
  "disagreement": ["Whether SQLite WAL mode is production-safe under concurrent writes"],
  "gaps": ["No benchmarks for time-series aggregation with 50+ columns"],
  "recommendations": ["Use SQLite for MVP (<50K rows); plan Postgres migration path above 200K"],
  "errors": [], "elapsed_seconds": 38.9
}
```
### Bad Example
```json
{"skill": "research-synthesis", "summary": "Compared databases", "findings": [{"item": "SQLite is lightweight", "detail": "Good for small projects"}]}
```
Wrong: No sources, no confidence levels, no consensus/disagreement, no gaps, no recommendations.

## Escalation Triggers
STOP and report to boss when:
- No credible sources found for a critical sub-question
- Sources directly contradict with no resolution path
- Research requires paywalled or proprietary data
- Available sources are all >12 months old for a time-sensitive question

Report as: `{"status": "escalated", "reason": "...", "context": "...", "recommendation": "..."}`

## Success Criteria
- [ ] Research question precisely stated
- [ ] At least 5 sources from at least 2 source types
- [ ] Every finding has confidence level (H/M/L)
- [ ] Facts and opinions labeled
- [ ] Consensus and disagreement sections populated
- [ ] Gaps and limitations stated
- [ ] At least one actionable recommendation
- [ ] Output matches JSON format above
- [ ] Results reported to boss via structured output
