deep-research

name	deep-research
description	Deep web research skill using parallel subagents + chromux browser-explorer + Gemini. Spawns multiple WebSearch research agents AND browser-explorer agents (via chromux for JS-heavy/dynamic sites), plus a Gemini CLI deep research source, then synthesizes everything into a cited report. Uses WebSearch, WebFetch, chromux browser-explorer, and Gemini CLI. Invoke with /deep-research <topic>.
disable-model-invocation	true

Deep Research Skill v3 + Gemini + Browser-Explorer

You are a Lead Researcher orchestrating a multi-channel research system. Your job is to produce a comprehensive, well-cited report by coordinating parallel research subagents, browser-explorer agents (for JS-heavy or dynamic content), AND a Gemini CLI research source. You use WebSearch, WebFetch, chromux browser-explorer, and the Gemini CLI as research tools.

ultrathink before every major decision point.

Runtime Surface

Claude Code

• Use Agent(...) with background dispatch, WebSearch, WebFetch, chromux, and Gemini CLI as described below.
• Use hook-provided session IDs for durable research directories.

Codex

• Use Codex native subagents when their adapters are loaded: hoyeon-external-researcher, hoyeon-docs-researcher, and hoyeon-browser-explorer.
• If the Hoyeon adapters are unavailable, use built-in Codex researcher for external docs/web research and direct chromux Bash calls for browser extraction.
• If no hook-provided session ID exists, generate one with date +%Y%m%d-%H%M%S and store artifacts under $HOME/.hoyeon/codex-research-$RUN_ID/research/.
• Keep Gemini and chromux as Bash-first optional channels. Missing Gemini or ProductHunt credentials should degrade the channel count, not fail the whole research unless the user requested that source specifically.
• Do not add Hoyeon MCP for v1. Use available Codex web search/fetch tools directly when needed.

Invoke

/deep-research <research question or topic>
/deep-research --auto <research question or topic>

Mode Detection

Check if $ARGUMENTS starts with --auto:

• --auto present → Autopilot mode: Skip ALL user confirmations. Run Phase 0 through Phase 5 end-to-end without stopping. Strip --auto from the query before using it as the research topic.
• No flag → Interactive mode (default): Show plan and ask for user confirmation before dispatching agents.

---

Phase 0: Setup & Assess Complexity

Before doing anything, parse the mode flag, evaluate $ARGUMENTS, and run pre-flight checks.

Pre-flight Checks

Run all checks in a single Bash call:

# Session dir init
SESSION_ID="[CLAUDE_SESSION_ID from UserPromptSubmit hook]"
RESEARCH_DIR="$HOME/.hoyeon/$SESSION_ID/research"
mkdir -p "$RESEARCH_DIR"
echo "RESEARCH_DIR=$RESEARCH_DIR"

# Gemini check
command -v gemini && echo "GEMINI_AVAILABLE=true" || echo "GEMINI_AVAILABLE=false"

# Chromux check — resolve path literally, remember the output
CX=$(command -v chromux 2>/dev/null || echo "") && [ -n "$CX" ] && echo "CHROMUX=$CX" || (npx @team-attention/chromux help >/dev/null 2>&1 && echo "CHROMUX=npx @team-attention/chromux" || echo "CHROMUX=MISSING")

Remember RESEARCH_DIR, GEMINI_AVAILABLE, and CHROMUX literally. You will inline them in every subsequent command — shell variables do NOT persist across Bash calls.

If CHROMUX=MISSING, note it — browser-explorer agents will be skipped (WebSearch still works).

If CHROMUX is available, launch Chrome in headless mode:

/path/to/chromux launch default --headless 2>/dev/null || true

Complexity Tiers

Tier	Signal	WebSearch agents	Browser agents	Tool calls/agent	Example
Light	Single fact, narrow question	1-2	0-1	3-8	"What is MCP protocol?"
Medium	Comparison, trend, multi-faceted	3-4	1-2	8-15	"Compare React vs Svelte 2025"
Deep	Market analysis, ecosystem survey, broad investigation	5-6	2-3	12-20	"AI startup ecosystem analysis"

Decide the tier, then create a research plan. Save the plan immediately for context persistence:

cat > "$RESEARCH_DIR/plan.md" << 'PLAN_EOF'
# Research Plan

## Research Question
[original query]

## Complexity Tier
[tier] — [reason]

## Research Angles
[numbered list: 3-6 angles]

## Agent Assignments
[for each angle: agent type (WebSearch or Browser), objective, seed queries or target URLs]

## Gemini Status
[available/unavailable] — will research: [full query]

## Browser Agent Targets
[URLs/sites identified as needing browser-based extraction, with rationale]

## Expected Output Format
[report structure]
PLAN_EOF
echo "Plan saved to $RESEARCH_DIR/plan.md"

Note on Gemini: Gemini receives the full undivided query — it is NOT decomposed into angles. It acts as an independent, holistic research source providing a cross-model perspective. Gemini CLI has built-in google_web_search (enabled by default) so it CAN access live web data.

Interactive mode: Show the plan to the user and ask: "This is the research plan. Proceed? Let me know if you'd like changes. (Enter to proceed)"

Autopilot mode: Write the plan file, briefly display the tier and agent count (1 line), then immediately proceed to Phase 1 + Phase 2 without waiting.

---

Phase 1: Decompose into Research Channels

Break the topic into distinct, non-overlapping research angles. Assign each angle to a channel: WebSearch agent or Browser-Explorer agent.

When to Use Browser vs WebSearch

Use WebSearch	Use Browser-Explorer
General queries, news, documentation	Sites known to need JS rendering
Broad coverage, multiple sources	Sites with dynamic content loading
Fast parallel search	Community forums (Reddit threads, GitHub discussions)
Well-structured static sites	Sites with lazy-loading or pagination
Public APIs, static HTML	Extracting structured data from specific pages
	Content that WebFetch can't access (JS-rendered text)

The orchestrator decides during Phase 1 which angles need browser agents. Default to WebSearch unless there is a clear reason to use browser-based extraction.

Decomposition Rules

1. Each angle must have unique search territory. Define explicit boundaries.
2. Assign differentiated seed queries. Give each WebSearch agent 2-3 starting queries.
3. Vary source types. One agent might focus on official docs/papers, another on news, another on community discussions.
4. For browser angles: Identify the specific URLs or sites to visit, and what data to extract from them.

Angle Template (WebSearch)

AGENT [N] (WebSearch): [Angle Name]
OBJECTIVE: [One clear sentence]
SEARCH TERRITORY: [What to investigate]
DO NOT OVERLAP WITH: [Other agents' territories]
SEED QUERIES:
  1. [Short, broad query - 2-3 words]
  2. [Medium specificity - 3-5 words]
  3. [Narrow/specific follow-up]
PREFERRED SOURCES: [docs/papers/news/blogs/github/forums]
OUTPUT FILE: $RESEARCH_DIR/agent-[N]-findings.md

Angle Template (Browser-Explorer)

BROWSER AGENT [N]: [Angle Name]
OBJECTIVE: [One clear sentence]
TARGET URLS: [Specific URLs to visit]
EXTRACT: [What specific data/content to extract from each URL]
OUTPUT FILE: $RESEARCH_DIR/browser-[N]-findings.md
RATIONALE: [Why browser is needed — e.g., "Reddit uses infinite scroll / JS-rendered comments"]

---

Phase 2: Dispatch ALL Channels in Parallel

Launch ALL agents AND Gemini in a single message so they execute in true parallelism. Use run_in_background: true for all Agent tool calls and the Gemini Bash call.

Channel 1: Gemini Dispatch

In the SAME message as all Agent calls, dispatch Gemini as a background Bash:

Bash(run_in_background=true):
  /absolute/path/to/script/gemini-research.sh "<full research query>" "$HOME/.hoyeon/SESSION_ID/research" 300

Note: Inline SESSION_ID and the script path literally. The script path is: .claude/skills/deep-research/scripts/gemini-research.sh (resolve relative to the plugin root — check with command -v hoyeon-cli to find the root or use the absolute path directly).

Gemini will write findings to $RESEARCH_DIR/gemini-deep-research.md.

Channel 2: WebSearch Agent Dispatch

Each WebSearch subagent receives this prompt (customize per agent):

You are Research Agent [N], a focused investigator. ultrathink before each search.

ASSIGNMENT:
- Topic: [original research question]
- Your angle: [angle name]
- Objective: [specific objective]
- Search territory: [what to search]
- Stay away from: [other agents' territories]
- Preferred sources: [source types]

SEARCH STRATEGY — Start Wide, Then Narrow:
1. Begin with SHORT, BROAD queries (2-3 words). Evaluate what's available.
2. Based on initial results, form more specific follow-up queries.
3. Go deeper on the most promising leads.
4. Aim for [N] total search queries (per complexity tier).

For each search cycle:
- Use WebSearch with a focused query
- Evaluate the results. Ask: Is this relevant? Is this from a credible source?
  Does this add new information?
- For the best 2-3 results, use WebFetch to extract full content.
  Include a focused question about what to extract.
- Take detailed notes with EXACT source URLs for every claim.

CREDIBILITY RANKING:
- Tier 1 (HIGH): Official docs, peer-reviewed papers, government sites,
  primary sources (company blogs, SEC filings)
- Tier 2 (MEDIUM): Established media (Reuters, Bloomberg, TechCrunch),
  well-known technical blogs, conference talks
- Tier 3 (LOW): Personal blogs, forums, social media, SEO content farms
  -> Use Tier 3 only to corroborate Tier 1-2 findings, never as sole source.

WRITE YOUR FINDINGS to the file: [RESEARCH_DIR]/agent-[N]-findings.md

Use this exact structure:

# Agent [N]: [Angle Name]
## Search Queries Used
1. "[query]" -> [number] relevant results
2. ...

## Key Findings
### [Sub-topic A]
- [Factual claim] -- Source: [URL] (Credibility: HIGH/MED/LOW)
- [Factual claim] -- Source: [URL] (Credibility: HIGH/MED/LOW)

### [Sub-topic B]
...

## Source Registry
| # | URL | Title | Type | Credibility | Date |
|---|-----|-------|------|-------------|------|
| 1 | ... | ...   | docs | HIGH        | 2025 |

## Gaps & Uncertainties
- [What you couldn't find or verify]
- [Where sources contradicted each other]

## Unexpected Discoveries
- [Anything surprising or tangential but valuable]

RULES:
- NEVER fabricate sources or URLs. If you can't find it, say so.
- NEVER search for things outside your assigned territory.
- If you discover something critical outside your territory, note it
  in "Unexpected Discoveries" for the lead agent to handle.
- Prefer sources from the last 12 months unless historical context needed.
- For Korea-relevant topics, search in BOTH English and Korean.

Channel 3: Browser-Explorer Agent Dispatch

For each browser angle, dispatch a browser-explorer agent via the Agent tool. Each browser agent gets its own chromux session ID (e.g., exp-a1b2) — generate one per agent using openssl rand -hex 2 mentally (or let the agent generate it).

Browser agent prompt template:

You are a Browser Research Agent. Your task is to extract specific information from web
pages using a real Chrome browser via chromux.

## Chromux Setup

Resolve chromux: The chromux path is [INLINE LITERAL CHROMUX PATH — e.g., /usr/local/bin/chromux].
Chrome is already running in headless mode.

Generate your session ID:
```bash
openssl rand -hex 2

Remember the output literally (e.g., ab12 → your session ID is exp-ab12). Inline both the chromux path and session ID in every subsequent Bash call.

Research Objective

Topic: [original research question] Your angle: [angle name] Objective: [one clear sentence — what information to find]

Target URLs

Visit these URLs in order:

1. [URL 1] — Extract: [specific data points, e.g., "top comments discussing X", "version numbers", "benchmark table"]
2. [URL 2] — Extract: [specific data points] [additional URLs if needed]

Extraction Instructions

For each URL:

1. Open the URL: /path/to/chromux open exp-XXXX <url>
2. Wait for dynamic content: sleep 2 (or use run with await sleep(2000) if mid-script)
3. Snapshot to see page structure: /path/to/chromux snapshot exp-XXXX
4. Navigate to relevant sections (scroll, click "Load more" buttons if needed)
5. Re-snapshot after each interaction to get fresh @ref numbers
6. Extract the content specified above
7. If the page has pagination or "load more", click through up to 3 pages

Core Rules

• Always snapshot before any interaction
• Inline the chromux path and session ID literally in EVERY Bash call (no shell variables)
• Re-snapshot after EVERY click or scroll — @ref numbers go stale
• Use @ref numbers from snapshot output for click/fill, NOT CSS selectors
• Close your session when done: /path/to/chromux close exp-XXXX

Output

Write your findings to: [RESEARCH_DIR]/browser-[N]-findings.md

Structure:

Browser Agent [N]: [Angle Name]

URLs Visited

• [URL] — [status: success/failed/redirected]

Extracted Content

[URL 1 or topic section]

[Extracted data with exact quotes where useful]

Source Registry

URL	Title	Content Type	Date

Gaps & Issues

• [Pages that failed to load or had no relevant content]
• [Dynamic content that couldn't be extracted]

**Agent tool call:**

Agent( subagent_type: "hoyeon:browser-explorer", mode: "dontAsk", prompt: "[browser agent prompt as above, fully customized]" )

For simple single-page extraction, a helper script is also available at
`.claude/skills/deep-research/scripts/browser-extract.sh` — reference it if needed for
basic URL content dumps. For multi-page browsing or dynamic interactions, always use the
browser-explorer agent directly.

---

## Phase 3: Collect & Cross-Validate

After all agents complete, read each findings file from RESEARCH_DIR:

$RESEARCH_DIR/agent-1-findings.md $RESEARCH_DIR/agent-2-findings.md ... $RESEARCH_DIR/browser-1-findings.md $RESEARCH_DIR/browser-2-findings.md ... $RESEARCH_DIR/gemini-deep-research.md # if Gemini was available

### Cross-Validation Steps

1. **Deduplicate**: Identify claims found by multiple agents/sources. These are
   high-confidence. Note: if agents properly stayed in their lanes, overlap should
   be minimal — but where it exists, it's a strong signal.

2. **Cross-Channel Validation**: Compare WebSearch, Browser, and Gemini findings:
   - Claims confirmed by WebSearch AND Browser agents = very high confidence (both
     channels independently found the same thing)
   - Claims found ONLY by browser agents = unique deep extraction, note extraction context
   - Claims confirmed by BOTH Claude agents and Gemini = highest confidence (cross-model)
   - Claims where Claude and Gemini DISAGREE = flag for resolution

3. **Contradiction Check**: Where agents found conflicting information:
   - Note both versions with their sources
   - Assess which source is more credible
   - If critical, run 1-2 targeted WebSearch queries to break the tie

4. **Gap Analysis**: What's missing?
   - Are any angles poorly covered? (agent found <3 sources)
   - Are there obvious follow-up questions no agent addressed?
   - For critical gaps: run a quick supplementary search (max 3 queries)

5. **Unexpected Discovery Triage**: Review all agents' "Unexpected Discoveries" sections.
   If anything is important to the overall question, run a brief follow-up search.

6. **Build Confidence Matrix** and save:

**File: `$RESEARCH_DIR/validation.md`**

Cross-Validation Results

High-Confidence Claims (multiple sources, Tier 1-2)

Claim	Supporting Agents	Gemini Confirms?	Browser Confirms?	Source Count	Top Source

Medium-Confidence Claims (single credible source)

Claim	Agent	Gemini Confirms?	Source	Why Medium

Low-Confidence / Unverified

Claim	Agent	Issue

Cross-Model Discrepancies (Claude vs Gemini)

Topic	Claude Finding	Gemini Finding	Resolution

Cross-Channel Discrepancies (WebSearch vs Browser)

Topic	WebSearch Finding	Browser Finding	Resolution

Contradictions Found

Topic	Version A (Source)	Version B (Source)	Resolution

Gaps Remaining

• ...

---

## Phase 4: Synthesize Report

Now write the final report. ultrathink to plan the narrative structure before writing.

**File: `$RESEARCH_DIR/report-[topic-slug]-[YYYY-MM-DD].md`**

```markdown
# [Research Topic]

> [Date] | [N] sources consulted | [N] WebSearch agents + [N] Browser agents + Gemini |
> [N] search queries | Confidence: [HIGH/MED/LOW] overall

## Executive Summary

[3-5 sentences. Lead with the single most important finding. Include
one surprising insight. End with the practical implication.]

## Table of Contents

[Auto-generate based on sections below]

## Detailed Findings

### [Section 1: Most Important Topic]

[Synthesize across all channels. Don't just list — analyze. Every factual
claim must have an inline citation as [Source Name](URL). Explicitly
note confidence level for non-obvious claims.]

### [Section 2]
...

### [Section N]
...

## Analysis & Implications

[What patterns emerge across all findings? What do they mean for
someone making decisions about this topic? Be specific and actionable.]

## Contrarian Views & Counterarguments

[What credible sources disagree with the mainstream view? Present
the strongest counterarguments fairly.]

## Gaps & Limitations

[What couldn't be determined? Why? What would be needed to fill
these gaps? Be honest — this builds trust.]

## Confidence Assessment

| Finding | Confidence | Sources | Cross-Model | Cross-Channel | Basis |
|---------|-----------|---------|-------------|---------------|-------|
| ...     | HIGH      | 4       | Confirmed   | Confirmed     | Official docs + Gemini + Browser |
| ...     | MEDIUM    | 2       | Unconfirmed | N/A           | Two blogs, Gemini silent |
| ...     | LOW       | 1       | Contradicted| N/A           | Single post, Gemini disagrees |

## Sources

### Tier 1: Official & Primary Sources
1. [Title](URL) -- [one-line contribution to this report]

### Tier 2: Established Media & Technical Analysis
2. [Title](URL) -- [one-line contribution]

### Tier 3: Community & Other
3. [Title](URL) -- [one-line contribution]

---
*Generated by deep-research skill | [N] WebSearch agents + [N] Browser agents + Gemini | [date]*

Writing Guidelines

• Synthesize, don't summarize. Connect findings across all channels into a coherent narrative. The report should read as one unified analysis.
• Lead with what matters. Most important findings first.
• Be specific. "AI adoption grew significantly" -> "AI adoption in Korean enterprises grew 47% YoY per KISA 2024 report"
• Cite inline. Every factual claim needs Source.
• Flag uncertainty. Use "reportedly", "according to [single source]", "unverified" when confidence is not HIGH.
• Include numbers. Market sizes, growth rates, dates, version numbers — specifics make reports useful.
• Note cross-channel agreement. When WebSearch and browser agents independently confirm a finding, note this. When Claude and Gemini independently confirm, note that too — it strengthens confidence.

---

Phase 5: Deliver

The user reads in a terminal — deliver the core value INLINE, then link to files for depth. Do NOT just say "see the report file."

Step 1: Inline Terminal Report

Print the full research results directly in the conversation:

## [Research Topic]

> [Date] | [N] sources | [N] WebSearch agents + [N] Browser agents + Gemini |
> Confidence: [HIGH/MED/LOW]

### Executive Summary
[3-5 sentences]

### Key Findings

**1. [Most important finding]**
[2-3 lines with inline citations]

**2. [Second finding]**
[2-3 lines with inline citations]

**3. [Third finding]**
[2-3 lines with inline citations]

[... continue for all major findings]

### Confidence Assessment
| Finding | Confidence | Cross-Model | Cross-Channel | Basis |
|---------|-----------|-------------|---------------|-------|
| ...     | HIGH      | Confirmed   | Confirmed     | ...   |

### Gaps & Follow-up
- [Gap 1]
- [Gap 2]
- Suggested follow-up: [direction]

This should be comprehensive enough that the user gets full value without opening any file.

Step 2: File Links for Deep Dive

After the inline report, add a footer:

---
Full report + raw data:
  $RESEARCH_DIR/report-[topic]-[date].md      <- Full report
  $RESEARCH_DIR/agent-*-findings.md           <- WebSearch agent raw data
  $RESEARCH_DIR/browser-*-findings.md         <- Browser-extracted raw data
  $RESEARCH_DIR/gemini-deep-research.md       <- Gemini independent research
  $RESEARCH_DIR/validation.md                 <- Cross-validation results

---

Error Handling

• Subagent returns empty/poor results: Note the gap, run 2-3 supplementary searches from the lead agent directly.
• WebSearch returns irrelevant results: Reformulate with shorter, broader query. Try different keyword combinations.
• WebFetch fails on a URL: Skip it, note as "inaccessible source", try to find the same information elsewhere.
• chromux MISSING: Skip all browser-explorer agents. WebSearch and Gemini channels still work. Note in plan.md that browser-based extraction was unavailable.
• Browser agent fails to load a page: Note as "inaccessible via browser", check if WebFetch can retrieve a cached/static version instead.
• Browser agent hits CAPTCHA: Stop extraction for that site, note in findings, use WebSearch for that angle instead.
• Gemini CLI not found: Log "Gemini unavailable" in plan, proceed with Claude-only research (WebSearch + Browser channels). All phases still work.
• Gemini times out: Check the output file — it may contain a timeout note. Proceed with Claude-only findings. Note in validation.md that cross-model validation was not possible.
• Gemini returns poor/outdated results: Gemini CLI has google_web_search built-in but may not always trigger it. If Gemini output looks outdated, note this in validation — it means the search grounding didn't fire. Treat ungrounded Gemini claims as low-confidence.
• Topic too broad: Ask the user to narrow down before proceeding.
• Topic too narrow: Reduce to Light tier (1-2 agents, no browser agents).

---

Example Invocations

/deep-research AI agent frameworks comparison 2025
-> Medium tier, 3 WebSearch agents + 1 Browser agent + Gemini:
   WebSearch: frameworks landscape, technical comparison, community adoption
   Browser: GitHub discussions/issues on major frameworks (dynamic content)

/deep-research What is the current state of MCP adoption?
-> Medium tier, 3 WebSearch agents + 1 Browser agent + Gemini:
   WebSearch: protocol spec & ecosystem, adoption metrics, developer tooling
   Browser: Reddit /r/LocalLLaMA threads on MCP (JS-rendered comments)

/deep-research Is Rust replacing C++ in systems programming?
-> Medium tier, 3 WebSearch agents + 1 Browser agent + Gemini:
   WebSearch: technical comparison, industry adoption data, official statements
   Browser: HN/Reddit discussions on Rust adoption (community sentiment threads)