research-topic

What this skill does

# Multi-Source Deep Research

You are orchestrating parallel deep research across three LLM providers (Anthropic Claude, OpenAI GPT, Google Gemini) using native `context: fork` subagents and synthesizing the results into a unified deliverable.

**Architecture:** Three subagents dispatch in parallel — one per provider. Each subagent makes its provider's API call directly (via `curl` or SDK) and writes a structured findings file to `reports/`. Parent skill reads all three outputs and synthesizes the unified report.

**Trade-offs vs Previous Implementation:** This architecture eliminates the Python research-orchestrator tool and all its dependencies (no pip installs, no virtual env, no PYTHONPATH setup). Trade-off: no real-time streaming progress bars during API polling. For long runs (30+ min), watch the in-progress agent indicators in the Claude Code UI. Architecture gains: simpler debugging, cross-platform portability, single-runtime execution.

## Proactive Triggers

Suggest this skill when:
1. User asks to research a topic in depth or wants a comprehensive analysis
2. User wants to compare perspectives across multiple AI providers
3. User needs a well-sourced analysis that benefits from multi-source synthesis
4. User mentions "deep research", "research report", or "multi-provider analysis"
5. User asks for a thorough investigation of a technical, strategic, or emerging topic

## Input Validation

**Required Arguments:**
- Research request (provided by user as $ARGUMENTS or in conversation)

**Optional Arguments:**
- `--sources <list>` - Comma-separated list of sources to use: `claude`, `openai`, `gemini` (default: all three)
- `--depth <level>` - Research depth: `brief`, `standard`, `comprehensive` (default: standard)
- `--format <type>` - Output format: `md`, `docx`, `both` (default: both)
- `--no-clarify` - Skip clarification loop, use request as-is
- `--no-audience` - Skip audience profile detection, use default profile

**Environment Requirements:**
API keys must be loaded into the environment before use. Run `/unlock` to load secrets from Bitwarden Secrets Manager via the `bws` CLI (see CLAUDE.md Secrets Management Policy):
- `ANTHROPIC_API_KEY` - For Claude with Extended Thinking
- `OPENAI_API_KEY` - For OpenAI Deep Research
- `GOOGLE_API_KEY` - For Gemini Deep Research

If keys are not in the environment, suggest running `/unlock` before proceeding. Do NOT write API keys to `.env` files.

**Optional Model Configuration (non-sensitive, safe for .env):**
- `ANTHROPIC_MODEL` - Override Claude model. Default: `claude-opus-4-6-20250725`
- `OPENAI_MODEL` - Override OpenAI model. Default: `o3-deep-research-2025-06-26`
- `GEMINI_AGENT` - Override Gemini agent. Default: `deep-research-pro-preview-12-2025`

For provider configurations, depth parameter mappings, and cost estimates, read `references/research-models.md` (relative to this plugin's directory).

## Workflow

### Phase 1: Intake

Accept the research request from the user. If no request is provided in arguments, prompt:
```text
What would you like to research?

Please describe your research question or topic. Include any relevant context
about scope, audience, or specific aspects you want explored.
```

### Phase 1.5: Audience Profile Detection

**Purpose:** Tailor research output to the user's profile.

**Step 1: Search for Existing Profile**

Search for an audience/user profile in CLAUDE.md files in this priority order:
1. **Project:** `./CLAUDE.md` or `./.claude/CLAUDE.md`
2. **Local:** `./.claude.local/CLAUDE.md`
3. **Global:** `~/.claude/CLAUDE.md` (Windows: `%USERPROFILE%\.claude\CLAUDE.md`)

Look for sections matching: `# Audience Profile`, `# User Profile`, `# Target Audience`, `# Reader Profile`, or name-prefixed variants.

**Step 2A: If Profile Found** — Display a summary (Role, Background, Preferences) with source path. Ask user to confirm or modify.

**Step 2B: If No Profile Found** — Prompt user to describe their target audience. Offer to save the profile to `~/.claude/CLAUDE.md` for future sessions.

**Step 3: Store for Session** — Store the confirmed profile for use in Phase 4 prompt construction.

**Skip Conditions:** Skip with `--no-audience` flag or if user says "skip"/"none" (use default profile).

### Phase 2: Clarification Loop (max 4 rounds)

**REQUIRED:** Unless `--no-clarify` is specified, run the clarification loop before proceeding.

Ask clarifying questions across these dimensions:

| Dimension | Question Type |
|-----------|---------------|
| **Scope** | Breadth vs depth, specific subtopics to include/exclude |
| **Audience** | Technical level, domain expertise assumed |
| **Depth** | Summary vs comprehensive analysis |
| **Deliverable** | Report structure, key sections needed |
| **Recency** | How current must information be? |

- Ask 1-4 questions per round
- Stop when request is sufficiently defined OR 4 rounds complete
- Provide sensible defaults for skipped questions

### Phase 3: Pre-Execution Gate

**Step 1: Check API Key Availability**

Check which provider API keys are present in the environment:

```bash
# Check which keys are available
echo "ANTHROPIC_API_KEY: $([ -n "$ANTHROPIC_API_KEY" ] && echo 'PRESENT' || echo 'MISSING')"
echo "OPENAI_API_KEY: $([ -n "$OPENAI_API_KEY" ] && echo 'PRESENT' || echo 'MISSING')"
echo "GOOGLE_API_KEY: $([ -n "$GOOGLE_API_KEY" ] && echo 'PRESENT' || echo 'MISSING')"
```

**If any requested provider keys are missing:**
```text
Pre-Execution Check: PARTIAL/FAILED

Missing API keys:
  - ANTHROPIC_API_KEY (required for claude source)
  - OPENAI_API_KEY (required for openai source)
  - GOOGLE_API_KEY (required for gemini source)

To load API keys from Bitwarden, run: /unlock
```

**If all keys present for selected sources:**
```text
Pre-Execution Check: PASSED
API keys configured for: [list of available providers]
```

**Handling missing keys gracefully:** If a provider key is missing, skip that provider's subagent dispatch. Proceed with the available providers and note the skip in the output. Do not abort unless ALL selected providers are missing keys.

**Step 2: Present the research brief:**

```yaml
Research Brief
==============
Topic: [refined topic statement]
Scope: [defined boundaries]
Depth: [brief/standard/comprehensive]
Sources: [providers that will be used — skip any with missing keys]
Skipped: [providers skipped due to missing API keys, if any]
Deliverable: [expected output structure]

Target Audience:
  Role: [from Phase 1.5 profile]
  Background: [key expertise areas]
  Preferences: [communication style]

Proceed with this research brief? (yes/revise)
```

Wait for user confirmation.

### Phase 4: Parallel Provider Research via context:fork Subagents

**Resolve model names before dispatch:**

```bash
# Resolve model identifiers (env var override or defaults)
CLAUDE_MODEL="${ANTHROPIC_MODEL:-claude-opus-4-6-20250725}"
OAI_MODEL="${OPENAI_MODEL:-o3-deep-research-2025-06-26}"
GEMINI_AGENT_ID="${GEMINI_AGENT:-deep-research-pro-preview-12-2025}"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
echo "CLAUDE_MODEL=$CLAUDE_MODEL"
echo "OAI_MODEL=$OAI_MODEL"
echo "GEMINI_AGENT_ID=$GEMINI_AGENT_ID"
echo "TIMESTAMP=$TIMESTAMP"
```

**Craft the Research Prompt:**

Transform the refined brief into a provider-agnostic prompt including the audience profile from Phase 1.5. If Phase 1.5 was skipped, use the default profile: Senior Director/VP-level technology executive; enterprise software architecture, AI/ML systems, cloud infrastructure; prefers actionable insights and data-driven recommendations; comfortable with technical details but values strategic framing.

```text
Research Request: [topic]

Context:
- Scope: [boundaries]
- Depth: [level]

Target Audience Profile:
[INSERT AUDIENCE PROFILE FROM PHASE 1.5 HERE]

Please provide a comprehensive analysis covering:
1. [Key aspect 1 — derived from clarification]
2. [Key aspect 2]
3. [Key aspect 3]

Structure your response with:
- Executive summary (2-3 key takeaways)
- Detailed analysis with su