research

Purpose

Web research utility. Receives a research question, executes targeted searches, deep-dives into top results, and returns structured findings with sources. Stateless — no memory between calls.

Calls (outbound)

None — pure L3 utility using WebSearch and WebFetch tools directly.

Called By (inbound)

• plan (L2): external knowledge for architecture decisions
• brainstorm (L2): data for informed ideation
• marketing (L2): competitor analysis, SEO data
• hallucination-guard (L3): verify package existence on npm/pypi
• autopsy (L2): research best practices for legacy patterns
• ba (L2): research similar products and integrations
• graft (L2): research source repo patterns before grafting
• mcp-builder (L2): research MCP standards and existing implementations
• scaffold (L1): research project templates and best practices

Execution

Input

research_question: string   — what to research
focus: string (optional)    — narrow the scope (e.g., "security", "performance")

Step 1 — Formulate Queries

Generate 2-3 targeted search queries from the research question. Vary phrasing to cover different angles:

• Primary: direct question as search terms
• Secondary: "[topic] best practices 2026" or "[topic] vs alternatives"
• Tertiary: "[topic] example" or "[topic] tutorial" if implementation detail needed

Step 2 — Search (Minimum 3 Complementary Sources)

Call WebSearch for each query. Collect result titles, URLs, and snippets. Identify the top 3-5 most relevant URLs prioritizing source diversity:

Source Type	Examples	Why
Official docs	Framework docs, API reference, RFC	Authoritative but may lag behind reality
Community	Stack Overflow, GitHub Issues, Reddit	Real-world pain points, edge cases
Technical blogs	Dev.to, Medium engineering blogs, personal blogs	Practical experience, tutorials
Repositories	GitHub repos, npm packages, example code	Working implementations

Selection rules:

• Source authority (official docs > major blogs > personal blogs)
• Recency (prefer 2025-2026)
• Relevance to the query
• Diversity: never select 3+ URLs from the same domain — spread across source types

Step 2b — Diminishing Returns Detection

After each WebSearch call, evaluate whether additional searches are productive:

Track across search results:

• Entity set: Extract key entities from each result set (library names, API names, version numbers, technique names, company names)
• New entity ratio: new_entities_in_this_search / total_entities_found_so_far
• Result overlap: How many URLs from this search were already seen in previous searches

Signal	Threshold	Action
New entity ratio < 10%	Last search added almost nothing new	Skip remaining queries, proceed to Step 3 with existing results
Result overlap > 60%	Most URLs already fetched or seen	Skip this query's results entirely
All 3 queries return same top 3 URLs	Search space is exhausted	Proceed directly to Step 3 — more queries won't help

Report when triggered:

Note: Research saturation reached after [N] searches — [M] unique entities found.
Additional queries showed <10% new information. Proceeding with synthesis.

Why: Research skills commonly waste 2-3 WebFetch calls on pages that repeat information already gathered. Saturation detection saves tool calls and context tokens while preserving research quality — the first 3 sources typically contain 90%+ of available information.

Step 3 — Deep Dive

Call WebFetch on the top 3-5 URLs identified in Step 2. Hard limit: max 5 WebFetch calls per research invocation. For each fetched page:

• Extract key facts, API signatures, code examples
• Note the source URL and publication date if visible
• Tag the source type (official/community/blog/repo) for Step 4 triangulation

Step 4 — Synthesize (Triangulation)

Across all fetched content, triangulate — don't just aggregate:

• Identify points of consensus across sources (≥3 sources = strong signal)
• Flag any conflicting information explicitly (e.g., "Source A says X, Source B says Y")
• Check if conflicts are temporal (old vs new info) or genuine disagreement
• Assign confidence using source diversity:

Confidence	Criteria
high	3+ sources from different types agree
medium	2 sources agree, or 3+ from same type
low	Single source, or sources conflict without resolution
unverified	No sources found — report this explicitly, NEVER fabricate

Step 5 — Report

Return structured findings in the output format below.

Constraints

• Always cite source URL for every finding
• Flag conflicting information — never silently pick one side
• Max 5 WebFetch calls per invocation
• If no useful results found, report that explicitly rather than fabricating

Output Format

## Research Results: [Query]
- **Sources fetched**: [n]
- **Confidence**: high | medium | low

### Key Findings
- [finding] — [source URL]
- [finding] — [source URL]

### Conflicts / Caveats
- [Source A] says X. [Source B] says Y. Recommend verifying against [authority].

### Code Examples
```[lang]
[relevant snippet]

Recommendations

• [actionable suggestion based on findings]

## Sharp Edges

Known failure modes for this skill. Check these before declaring done.

| Failure Mode | Severity | Mitigation |
|---|---|---|
| Fabricating findings when no useful results found | CRITICAL | Constraint: report "no useful results found" explicitly — never invent citations |
| Reporting conflicting sources without flagging the conflict | HIGH | Constraint: flag conflicting information explicitly, never silently pick one side |
| Assigning "high" confidence from a single source | MEDIUM | High = 3+ sources agree; 1-2 sources = medium confidence |
| Exceeding 5 WebFetch calls per invocation | MEDIUM | Hard limit: prioritize top 3-5 URLs from search, fetch only the most relevant |
| Single-source conclusions presented as fact | HIGH | HARD-GATE: minimum 3 complementary sources from different source types. Single source = `low` confidence |
| All sources from same domain (e.g., 3 Stack Overflow links) | MEDIUM | Source diversity rule: never 3+ URLs from the same domain. Spread across official/community/blog/repo |

## Done When

- 2-3 search queries formulated and executed
- Top 3-5 URLs identified and fetched (max 5 WebFetch calls)
- Conflicting information between sources explicitly flagged
- Confidence level assigned (high/medium/low) with rationale
- Research Results emitted with source URLs for every key finding

## Cost Profile

~300-800 tokens input, ~200-500 tokens output. Haiku. Fast and cheap.