/research-external

name: research-external
description: External research workflow for docs, web, APIs - NOT codebase exploration
model: sonnet
allowed-tools: [Bash, Read, Write, Task]

External Research Workflow

Research external sources (documentation, web, APIs) for libraries, best practices, and general topics.

> **Note:** The current year is 2025. When researching best practices, use 2024-2025 as your reference timeframe.

Invocation

/research-external <focus> [options]

Question Flow (No Arguments)

If the user types just `/research-external` with no or partial arguments, guide them through this question flow. Use AskUserQuestion for each phase.

Phase 1: Research Type

question: "What kind of information do you need?"
header: "Type"
options:
  - label: "How to use a library/package"
    description: "API docs, examples, patterns"
  - label: "Best practices for a task"
    description: "Recommended approaches, comparisons"
  - label: "General topic research"
    description: "Comprehensive multi-source search"
  - label: "Compare options/alternatives"
    description: "Which tool/library/approach is best"

**Mapping:**

• "How to use library" → library focus
• "Best practices" → best-practices focus
• "General topic" → general focus
• "Compare options" → best-practices with comparison framing

Phase 2: Specific Topic

question: "What specifically do you want to research?"
header: "Topic"
options: []  # Free text input

Examples of good answers:

• "How to use Prisma ORM with TypeScript"
• "Best practices for error handling in Python"
• "React vs Vue vs Svelte for dashboards"

Phase 3: Library Details (if library focus)

If user selected library focus:

question: "Which package registry?"
header: "Registry"
options:
  - label: "npm (JavaScript/TypeScript)"
    description: "Node.js packages"
  - label: "PyPI (Python)"
    description: "Python packages"
  - label: "crates.io (Rust)"
    description: "Rust crates"
  - label: "Go modules"
    description: "Go packages"

Then ask for specific library name if not already provided.

Phase 4: Depth

question: "How thorough should the research be?"
header: "Depth"
options:
  - label: "Quick answer"
    description: "Just the essentials"
  - label: "Thorough research"
    description: "Multiple sources, examples, edge cases"

**Mapping:**

• "Quick answer" → --depth shallow
• "Thorough" → --depth thorough

Phase 5: Output

question: "What should I produce?"
header: "Output"
options:
  - label: "Summary in chat"
    description: "Tell me what you found"
  - label: "Research document"
    description: "Write to thoughts/shared/research/"
  - label: "Handoff for implementation"
    description: "Prepare context for coding"

**Mapping:**

• "Research document" → --output doc
• "Handoff" → --output handoff

Summary Before Execution

Based on your answers, I'll research:

**Focus:** library
**Topic:** "Prisma ORM connection pooling"
**Library:** prisma (npm)
**Depth:** thorough
**Output:** doc

Proceed? [Yes / Adjust settings]

Focus Modes (First Argument)

| Focus | Primary Tool | Purpose | |-------|--------------|---------| | `library` | nia-docs | API docs, usage patterns, code examples | | `best-practices` | perplexity-search | Recommended approaches, patterns, comparisons | | `general` | All MCP tools | Comprehensive multi-source research |

Options

| Option | Values | Description | |--------|--------|-------------| | `--topic` | `"string"` | **Required.** The topic/library/concept to research | | `--depth` | `shallow`, `thorough` | Search depth (default: shallow) | | `--output` | `handoff`, `doc` | Output format (default: doc) | | `--library` | `"name"` | For `library` focus: specific package name | | `--registry` | `npm`, `py_pi`, `crates`, `go_modules` | For `library` focus: package registry |

Workflow

Step 1: Parse Arguments

Extract from user input:

FOCUS=$1           # library | best-practices | general
TOPIC="..."        # from --topic
DEPTH="shallow"    # from --depth (default: shallow)
OUTPUT="doc"       # from --output (default: doc)
LIBRARY="..."      # from --library (optional)
REGISTRY="npm"     # from --registry (default: npm)

Step 2: Execute Research by Focus

Focus: `library`

Primary tool: **nia-docs** - Find API documentation, usage patterns, code examples.

# Semantic search in package
(cd $CLAUDE_OPC_DIR && uv run python -m runtime.harness scripts/mcp/nia_docs.py \
  --package "$LIBRARY" \
  --registry "$REGISTRY" \
  --query "$TOPIC" \
  --limit 10)

# If thorough depth, also grep for specific patterns
(cd $CLAUDE_OPC_DIR && uv run python -m runtime.harness scripts/mcp/nia_docs.py \
  --package "$LIBRARY" \
  --grep "$TOPIC")

# Supplement with official docs if URL known
(cd $CLAUDE_OPC_DIR && uv run python -m runtime.harness scripts/mcp/firecrawl_scrape.py \
  --url "https://docs.example.com/api/$TOPIC" \
  --format markdown)

**Thorough depth additions:**

• Multiple semantic queries with variations
• Grep for specific function/class names
• Scrape official documentation pages

Focus: `best-practices`

Primary tool: **perplexity-search** - Find recommended approaches, patterns, anti-patterns.

# AI-synthesized research (sonar-pro)
(cd $CLAUDE_OPC_DIR && uv run python scripts/mcp/perplexity_search.py \
  --research "$TOPIC best practices 2024 2025")

# If comparing alternatives
(cd $CLAUDE_OPC_DIR && uv run python scripts/mcp/perplexity_search.py \
  --reason "$TOPIC vs alternatives - which to choose?")

**Thorough depth additions:**

# Chain-of-thought for complex decisions
(cd $CLAUDE_OPC_DIR && uv run python scripts/mcp/perplexity_search.py \
  --reason "$TOPIC tradeoffs and considerations 2025")

# Deep comprehensive research
(cd $CLAUDE_OPC_DIR && uv run python scripts/mcp/perplexity_search.py \
  --deep "$TOPIC comprehensive guide 2025")

# Recent devel