deep-research

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).
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:
   • Comprehensive Brief — for landscape/state-of-the-art research
   • Comparison Brief — for head-to-head evaluations
2. 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
3. Cite every claim — link to the source URL inline. Use the format: [Source Name](URL).
4. 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.

1. Review the gap analysis section of your report.
2. For each fillable gap:
   • Run 1-2 targeted searches with refined queries
   • Extract and read the results
   • Update the report artifact in-place
3. Max 3 total iterations (Phase 1-3 = round 1, then up to 2 more targeted rounds).
4. 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