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
- Decompose the topic into 3-5 research axes.
- Example: "Compare Next.js vs Remix" → Performance, DX, Ecosystem, Deployment, Community
- Identify the decision context — what is the user actually deciding?
- Framework choice? Architecture pattern? Build vs buy? Migration risk?
- 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.
- 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
- 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
- Collect 15-25 candidate URLs, not 5. Score each by authority tier (see references/research-heuristics.md).
- 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.
- Select the top 8-12 sources from Phase 1 (prioritize S and A tier).
- 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
- 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
- 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.
- Choose the report template from references/report-templates.md:
- Comprehensive Brief — for landscape/state-of-the-art research - Comparison Brief — for head-to-head evaluations
- Write the report as a rich markdown artifact:
- Narrative prose in the executive summary — not bullets, not lists. Write as if briefing a tech lead. - Comparison tables with real data extracted from sources - Mermaid diagrams for architecture, decision trees, ecosystem maps - Embedded screenshots captured via browser_subagent during Phase 2 - Code examples pulled from actual repos or docs - Use generate_image for custom visualizations when no screenshot captures the concept
- Cite every claim — link to the source URL inline. Use the format:
[Source Name](URL). - Gap analysis — explicitly call out:
- What couldn't be determined and why - Conflicting information between sources - Areas where only low-tier sources were found
Output: The research artifact (e.g., research_report.md).
Phase 4: Iteration
Goal: Fill gaps identified in Phase 3.
- Review the gap analysis section of your report.
- For each fillable gap:
- Run 1-2 targeted searches with refined queries - Extract and read the results - Update the report artifact in-place
- Max 3 total iterations (Phase 1-3 = round 1, then up to 2 more targeted rounds).
- After final iteration, mark remaining gaps as "Unresolved" with explanation.
Agentic Workflow & Vibe Coding
- Iterative Synthesis: Do not expect a perfect, comprehensive report on the first draft. Write the initial synthesis, review the extracted data and formatting, isolate any specific gaps or broken diagrams, refine ONE section at a time, and regenerate until the artifact meets the briefing standards.
- Vibe Coding: Commit your working markdown report and any local screenshots/assets locally *before* kicking off additional deep-read loops, ensuring you don't lose the structural foundation if a search goes off track.
Tool Strategy
| Purpose | Primary | Fallback |
|---|---|---|
| Topic discovery | search (Firecrawl) | search_web |
| Delegated deep research | search + scrape | Manual multi-search |
| Full page extraction | scrape (Firecrawl) | read_url_content |
| Multi-page docs | crawl (Firecrawl) | search + manual |
| Visual evidence | browser_subagent (screenshot) | generate_image |
| GitHub analysis | search_code, get_file_contents | read_url_content on raw GitHub |
| Architecture diagrams | Mermaid in markdown | generate_image |
| Data visualization | Markdown tables | generate_image for charts |
Quality Gates
Before delivering the report, verify:
- Source diversity — at least 1 S-tier and 2 A-tier sources cited (or explicitly flagged as unavailable)
- Visual richness — at least 1 screenshot/image AND 1 diagram/table embedded
- Narrative quality — executive summary reads as prose, not bullet points
- Citation completeness — every factual claim links to a source
- Gap transparency — gaps and conflicts are explicitly documented
- Actionable output — recommendations section exists with ranked, specific advice
Anti-Patterns
- Snippet-only research — stopping at search result descriptions without full extraction
- Text-wall reports — no visuals, no tables, no diagrams. The whole point is richness.
- Source-by-source organization — findings must be grouped thematically by research axis, not by URL
- Single-tool reliance — use at least 2 different search/extraction tools for source diversity
- Uncited claims — every substantive finding must link to its source
- Marketing echo — repeating a framework's own marketing claims without independent verification
- Premature stopping — delivering after 3-5 sources when the topic warrants 15+
Agentic OS Integration
If the current project root contains an .agent/ directory, this skill MUST participate in the Agentic OS shared-memory model.
At the end of your execution, check for .agent/state/last-run.json. If it exists, append or update the file using its required schema to log your run. Ensure you capture your runtime (agent_runtime), skill_executed, a concise summary, decisions, and next_steps.
References
- Source authority scoring and query patterns: references/research-heuristics.md
- Report structure templates: references/report-templates.md