/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