deep-research

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: deep-research
version: 1.1.0
description: Conduct comprehensive, multi-round research that produces rich visual reports. Use when asked for "deep research", "comprehensive analysis", "compare frameworks", "evaluate options", "research the state of X", or any task requiring investigation across 10+ sources. NOT for quick lookups — this is a 5-15 minute deep dive that produces a briefing-quality artifact with screenshots, diagrams, tables, and cited findings.
---

# Deep Research

Produce Gemini Deep Research-quality output: rich artifacts with embedded screenshots, mermaid diagrams, comparison tables, and narrative synthesis. Tuned for developer decisions — framework selection, architecture patterns, dependency evaluation, competitive analysis.

## When to Use This Skill

- "Research the current state of X"
- "Compare Framework A vs Framework B"
- "What are the best approaches for..."
- "Deep dive into..."
- Any request where the answer requires **synthesizing information from many sources**

**Do NOT use for**: quick factual lookups, single-source answers, or "find me a CSS button" (use `design-lookup` instead).

## Input Protocol — Before Any Search

1. **Decompose** the topic into 3-5 research axes.
   - Example: "Compare Next.js vs Remix" → Performance, DX, Ecosystem, Deployment, Community
2. **Identify the decision context** — what is the user actually deciding?
   - Framework choice? Architecture pattern? Build vs buy? Migration risk?
3. **Draft a research plan** — present 3-5 axes with planned queries to the user.
   - Save it as an artifact (e.g., `research_plan.md`).
   - Proceed on approval, or refine if the user redirects scope.

## Phase 1: Breadth Scan

**Goal**: Map the landscape. Find *what exists* before reading anything.

1. Run **5-8 parallel searches** across different axes. Use at least two tools:
   - `search` (Firecrawl) — broad topic queries
   - `search_web` (Google) — alternate search perspective
   - `search` with specific `scrapeOptions` — targeted discovery
2. **Dev-specific breadth**:
   - `search_code` or `search_repositories` — find relevant GitHub repos
   - Search npm trends, bundle sizes, download counts when evaluating packages
   - Search for migration stories: "migrating from X to Y" experience reports
3. Collect **15-25 candidate URLs**, not 5. Score each by authority tier (see [references/research-heuristics.md](references/research-heuristics.md)).
4. **Do not stop at snippets.** Snippets are for candidate selection only.

**Output**: Candidate source list with tier ratings. Present to user if interactive, or proceed if autonomous.

## Phase 2: Deep Read

**Goal**: Extract actual content — implementation details, code examples, benchmarks, data.

1. **Select the top 8-12 sources** from Phase 1 (prioritize S and A tier).
2. **Full extraction** — get the complete page content:
   - `scrape` (Firecrawl) or `read_url_content` for text-heavy pages
   - `crawl` (Firecrawl) to follow documentation multi-page structures
   - `browser_subagent` to **screenshot** key pages (UIs, dashboards, architecture diagrams)
   - `get_file_contents` (GitHub MCP) to read actual source code from repos
3. **Analyze each source**:
   - Extract specific claims, numbers, patterns, code examples
   - Note the authority tier and any bias (is this the framework's own marketing?)
   - Tag findings by research axis
4. **Self-correction**: If a source is fluff (marketing-only, thin tutorial, SEO filler):
   - Discard it
   - Run a refined follow-up search with more specific terms
   - Try adding: "benchmark", "technical deep dive", "lessons learned", "postmortem"

**Output**: Annotated source notes organized by axis.

## Phase 3: Synthesis

**Goal**: Build the research briefing artifact. This is the main deliverable.

1. **Choose the report template** from [references/report-templates.md](references/report-templates.md):
   - **Comprehensive Brief** — for landscape/state-of-the-art research
   - **Comparison Brie