web-research-external

name

web-research-external

description

Produces structured research documents or implementation handoffs by searching external sources — library docs, web, APIs — for a given topic. Scoped to library/API/framework lookups toward an implementation handoff; for general fact-finding or claim verification, use `web-research` instead. Use when: "research how to use [library]", "find best practices for [topic]", "compare [options]", "look up [API/framework] documentation". NOT for codebase exploration (use project-exploration for that).

Web Research External

Researches external sources — library documentation, web search, API references — and produces structured findings for decisions or implementation.

Description

Covers three research modes: library (API docs and usage patterns for a specific package), best-practices (recommended approaches, comparisons, anti-patterns via web search), and general (all available sources for comprehensive coverage). Output is either a chat summary, a dated research document, or an implementation handoff ready for a coding agent. This skill is distinct from project-exploration (local codebase) and research-synthesis (processing existing notes).

When to Use

• Looking up how to use a library or framework (npm, PyPI, crates.io, Go modules)
• Finding current best practices for a technology decision
• Comparing two or more approaches or tools
• Building implementation context before writing code
• Producing a research document to share with teammates or agents

Do not use for local codebase exploration — use project-exploration for that.

Workflow

Step 1: Clarify Intent

If focus, topic, or depth are not provided, guide the user through:

Research type:

• "How to use a library/package" → library focus
• "Best practices for a task" → best-practices focus
• "General topic research" → general focus
• "Compare options/alternatives" → best-practices with comparison framing

Topic: The specific library, concept, or question (e.g., "Prisma ORM connection pooling", "error handling in Python async").

Depth:

• "Quick answer" → shallow (essentials only)
• "Thorough research" → thorough (multiple sources, examples, edge cases)

Output format:

• "Summary in chat" → chat
• "Research document" → doc (write to file)
• "Handoff for implementation" → handoff (structured YAML for coding agent)

Show a confirmation summary before executing:

Focus: library | Topic: "Prisma ORM" | Depth: thorough | Output: doc
Proceed?

Step 2: Execute Research by Focus

Focus: library

Use WebFetch to pull official documentation, README, and API reference. Use WebSearch for usage examples.

1. WebFetch: official docs URL for the package
2. WebSearch: "{library} {topic} examples site:github.com OR site:stackoverflow.com"
3. WebSearch: "{library} changelog OR migration guide" (if version-specific)

For thorough depth: add multiple semantic queries, grep for specific function/class names in examples, scrape additional documentation pages.

Focus: best-practices

Use WebSearch with current-year framing.

1. WebSearch: "{topic} best practices 2025"
2. WebSearch: "{topic} vs alternatives comparison"
3. WebSearch: "{topic} common mistakes anti-patterns"

For thorough depth: add chain-of-thought comparison queries, recent developments search (last 3 months), and cross-reference findings from multiple sources.

Focus: general

Use all available research tools in sequence:

1. WebSearch for library documentation and API references
2. WebSearch for best practices and comparisons
3. WebFetch specific documentation pages found in step 2 results

For thorough depth: run all three with expanded queries; cross-reference findings between sources; follow links for deeper context.

Step 3: Synthesize Findings

Combine results across all sources into:

1. Key Concepts — Core ideas and terminology
2. Code Examples — Working examples from documentation
3. Best Practices — Recommended approaches
4. Pitfalls — Common mistakes to avoid
5. Alternatives — Other options considered
6. Sources — URLs for all citations

If a source is unavailable, continue with remaining sources and note the gap explicitly.

Step 4: Write Output

Output: doc

Write to: research/YYYY-MM-DD-{topic-slug}.md

---
date: {ISO timestamp}
type: external-research
topic: "{topic}"
focus: {focus}
depth: {depth}
sources: [count]
status: complete | partial | failed
---

# Research: {Topic}

## Summary
{2-3 sentence summary of findings}

## Key Findings

### {Source category}
{Findings from each source}

### Code Examples
{Working examples found}

## Best Practices
- {Practice 1}
- {Practice 2}

## Pitfalls to Avoid
- {Pitfall 1}

## Alternatives Considered
| Option | Pros | Cons |
|--------|------|------|

## Sources
- [{Source 1}]({url1})

Output: handoff

Write to: research/{topic-slug}-handoff.yaml

type: research-handoff
topic: "{topic}"
status: complete

findings:
  key_concepts: [concept1, concept2]
  code_examples:
    - pattern: "{pattern name}"
      code: |
        // example code
  best_practices: [practice1, practice2]
  pitfalls: [pitfall1]

recommendations: [rec1, rec2]

sources:
  - title: "{Source 1}"
    url: "{url1}"
    type: documentation | article | reference

implementation_notes: |
  Recommended approach: ...
  Key libraries: ...
  Avoid: ...

Output: chat

Return a structured summary in the conversation with key findings, code examples, and source URLs. No file written.

Step 5: Return Completion Summary

Research complete.

Topic: {topic}
Focus: {focus} | Depth: {depth}
Output: {path or "chat summary above"}
Sources: {N} sources cited

Key findings:
- {Finding 1}
- {Finding 2}
- {Finding 3}

Best Practices

• Confirm scope before researching. The Step 1 clarification summary (Focus: X | Topic: Y | Depth: Z | Output: W) prevents discovering a mismatch after hours of fetching. Always show it and wait for confirmation.
• Match depth to need. Shallow depth (essentials only) is correct for quick decisions; thorough depth is warranted before committing to an architectural choice or writing a spec.
• Prefer official docs over community content for library focus. GitHub READMEs and official documentation pages are authoritative; blog posts and Stack Overflow answers supplement them, not replace them.
• Attribute every claim. Never write a finding without naming its source. Unattributed synthesis looks authoritative but is unverifiable.
• Note gaps explicitly. If a source is unavailable or a question couldn't be answered, say so in the output. A partial result with honest gaps is more useful than a confident-sounding synthesis with hidden holes.
• One handoff per implementation target. If research feeds multiple agents or tasks, produce one handoff per recipient rather than a single omnibus document — agents need focused context, not everything.

---

Quality Checklist

Before delivering research output:

• Scope confirmed with user (focus, topic, depth, output format)
• At least 2 sources consulted for shallow depth; 4+ for thorough depth
• All claims attributed to specific sources with URLs
• Conflicting information across sources surfaced explicitly (not silently resolved)
• Unavailable or paywalled sources noted as gaps
• Output format matches the requested type (chat, doc, or handoff)
• doc output written to research/YYYY-MM-DD-{topic-slug}.md with valid frontmatter
• handoff output written as valid YAML with all required fields populated
• Status field reflects actual completion (complete, partial, or failed)
• Completion summary delivered to user with source count and key findings

---

Common Pitfalls

• Skipping the confirmation step — Diving straight into research without confirming focus/depth/output format often produces the wrong artifact at the wrong detail level
• Library focus without fetching official docs — Relying on web search results for a library question instead of fetching the official documentation page directly; the README and API reference are the ground truth
• Treating the first result as authoritative — The top search result is not necessarily the most accurate or current; cross-reference across at least two independent sources
• Writing findings in discovery order — Organizing output by the order sources were found rather than by theme or concept produces a list, not a synthesis
• Omitting the status field — Leaving status: out of the doc or handoff frontmatter makes it impossible for downstream consumers to know if the research is complete or partial
• Handoff for a chat-level question — A YAML implementation handoff for a quick factual question is over-engineering; use chat output for questions answerable in a paragraph

---

Related Skills

• web-research — Use for general-purpose web queries using Brave Search; web-research-external adds structured output modes (doc/handoff) and library-focused fetching on top of the same base capability
• project-exploration — Use for local codebase exploration; distinct from this skill which is for external sources only
• specification-writer — Natural downstream consumer of a handoff-format research output; feed the YAML directly into spec writing
• scan-community-repos — Use when the research target is community skill repositories rather than libraries or general topics

---

Output

A research document (.md) or implementation handoff (.yaml) with:

• Synthesized findings across all sources
• Working code examples
• Explicit source citations with URLs
• Status indicator (complete / partial / failed)
• Gap notes for any unavailable sources