web-research

name	web-research
description	Conduct structured web research with hypothesis tracking. Synthesizes information from multiple sources into actionable findings. Use for technical research, API docs, best practices. Triggers: web research, look up, search for, find documentation.
metadata	{"short-description":"Structured web research"}

User request: $ARGUMENTS

Conduct structured web research to gather external information, synthesize findings, and provide actionable recommendations.

Output file: /tmp/research-{YYYYMMDD-HHMMSS}-{topic-kebab-case}.md

Phase 1: Setup

1.1 Define Research Scope

Identify:

• Primary question: What are we trying to learn? (single clear question)
• Context: Why do we need this? What's the decision this informs?
• Success criteria: What would a good answer include?
• Scope boundary: What's explicitly NOT included in this research?

If $ARGUMENTS is vague: Ask user to clarify the primary question before proceeding.

1.2 Create Research Log

Path: /tmp/research-{YYYYMMDD-HHMMSS}-{topic-kebab-case}.md

# Research Log: {topic}
Started: {timestamp}

## Research Question
{Primary question}

## Context
{Why we need this, what decision it informs}

## Success Criteria
{What a good answer includes}

## Hypotheses
(populated in 1.3)

## Sources Consulted
(populated during research)

## Findings
(populated during research)

## Conflicts
(populated when sources disagree)

## Synthesis
(populated in Phase 3)

1.3 Form Initial Hypotheses

Before searching, document initial hypotheses:

## Hypotheses

1. H1: {What we think might be true}
   - Confidence: Low/Medium/High
   - Would falsify: {what evidence would disprove this}

2. H2: {Alternative possibility}
   - Confidence: Low/Medium/High
   - Would falsify: {what evidence would disprove this}

3. H3: {Another angle to consider}
   - Confidence: Low/Medium/High
   - Would falsify: {what evidence would disprove this}

Why hypotheses first: Prevents confirmation bias. You'll search for evidence both supporting AND refuting each hypothesis.

1.4 Create Todo List

Use update_plan:

- [ ] Research H1: {hypothesis}
- [ ] Research H2: {hypothesis}
- [ ] Research H3: {hypothesis}
- [ ] (expand as research reveals new angles)
- [ ] Synthesize findings

Phase 2: Research Loop

Memento Loop

For each hypothesis/question:

1. Mark todo in_progress
2. Search for evidence
3. Write findings immediately to research log
4. Update hypothesis status
5. Expand todos for new angles discovered
6. Mark todo completed
7. Repeat until all hypotheses resolved

NEVER proceed without writing findings — research log = external memory.

2.1 Search Strategically

For each hypothesis/question:

1. Formulate search queries

   • Start broad, then narrow based on results
   • Use technical terms and specific version numbers
   • Try multiple phrasings of the same concept
   • Include year for time-sensitive topics

2. Source priority (higher = more authoritative):

   Priority	Source Type	Use For
   1	Official documentation	Canonical behavior, API specs
   2	Source code (GitHub)	Ground truth implementation
   3	GitHub issues/discussions	Real-world problems, edge cases
   4	Stack Overflow (recent)	Common problems, solutions
   5	Technical blogs (reputable)	Tutorials, opinions, comparisons
   6	General articles	Background context only

3. Evaluate source quality

   • Is it official/authoritative?
   • Is it current (check publication date)?
   • Does it cite sources or show evidence?
   • Do multiple independent sources agree?
   • Is the author credible in this domain?

2.2 Document Findings

After each source, update research log immediately:

### Source: {title}
**URL**: {url}
**Date**: {publication date or "undated"}
**Authority**: Official | Expert | Community | Unknown
**Credibility**: High | Medium | Low
**Relevant to**: H1, H2

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

**Evidence**:
> "{Relevant quote}" — {source}

**Supports**: H1
**Refutes**: H2
**Conflicts with**: {other source, if any}

2.3 Update Hypotheses

As findings come in, update each hypothesis:

### H1: {hypothesis}
- Status: CONFIRMED | REFUTED | UNCERTAIN | NEEDS MORE DATA
- Confidence: Low | Medium | High
- Evidence: {summary of supporting/refuting evidence}
- Sources: {list}

2.4 Handle Conflicting Information

When sources disagree:

1. Check dates — newer often supersedes older
2. Check authority — official > community > individual
3. Check specificity — exact version > general statement
4. Check consensus — 5 sources agreeing > 1 outlier
5. Note the conflict in research log:

## Conflicts

### {Topic of disagreement}
**Position A**: {claim} — supported by {sources}
**Position B**: {claim} — supported by {sources}
**Resolution**: {your assessment} or "Unresolved - present both"

2.5 Know When to Stop

Stop researching when:

• Primary question is answered with high confidence
• Multiple authoritative sources agree
• Hypotheses are resolved (confirmed or refuted)
• Further searching yields diminishing returns
• You've hit time/effort limits

Diminishing returns signals:

• Same information appearing across sources
• No new hypotheses emerging
• Low-quality sources dominating results

Phase 3: Synthesis

3.1 Refresh Context

Read the full research log before synthesizing. This restores all findings to recent context.

3.2 Write Synthesis

## Synthesis

### Answer to Primary Question
{Direct answer with confidence level: High/Medium/Low}

### Key Findings
1. {Most important finding with source}
2. {Second finding with source}
3. {Third finding with source}

### Hypothesis Resolution
- H1: {CONFIRMED/REFUTED/UNCERTAIN} — {evidence summary}
- H2: {CONFIRMED/REFUTED/UNCERTAIN} — {evidence summary}
- H3: {CONFIRMED/REFUTED/UNCERTAIN} — {evidence summary}

### Evidence Summary
- {Finding} supported by {N} authoritative sources
- {Finding} has conflicting information: {explain disagreement}

### Caveats and Limitations
- {What we couldn't verify}
- {Where information was sparse}
- {Potential biases in sources}
- {Time-sensitivity of findings}

### Recommendations
1. {Actionable recommendation with rationale}
2. {Alternative approach and when to use}
3. {What to watch out for}

### Sources (by authority)
**Official**:
- {Source with URL}

**Expert/Community**:
- {Source with URL}

**Other**:
- {Source with URL}

3.3 Present Summary

## Research Summary

**Question**: {Primary question}
**Confidence**: High | Medium | Low
**Research log**: /tmp/research-{...}.md

### Answer
{Concise direct answer}

### Key Findings
- {Finding 1}
- {Finding 2}
- {Finding 3}

### Recommendations
1. {What to do}
2. {What to avoid}
3. {What to monitor}

### Caveats
- {Key limitation or uncertainty}

### Top Sources
- {Most authoritative source with URL}
- {Second source with URL}

Guidelines

DO

• Document hypotheses BEFORE searching (reduces confirmation bias)
• Record ALL sources consulted, even unhelpful ones
• Note contradictions between sources explicitly
• Cite specific sources for claims
• Acknowledge uncertainty and limitations
• Update research log after EACH source
• Include publication dates for all sources

DON'T

• Cherry-pick sources that confirm expectations
• Trust single sources for important claims
• Ignore publication dates (outdated info is dangerous)
• Present opinions as facts
• Skip the synthesis step
• Make claims without source attribution
• Assume first result is best result

Source Authority Hierarchy

1. Official docs — Highest authority for how things are supposed to work
2. Source code — Ground truth for how things actually work
3. GitHub issues — Real-world problems, edge cases, workarounds
4. Stack Overflow — Community solutions (CHECK DATES!)
5. Technical blogs — Opinions and tutorials (verify claims)
6. General articles — Background only, never cite for specifics

Time Sensitivity

For technical topics:

• Web frameworks: 6-12 months (rapidly changing)
• Languages: 1-2 years (slower changing)
• CS fundamentals: 5+ years (stable)
• Security: 3-6 months (actively exploited)

Always note when information might be outdated.

Edge Cases

Case	Action
No relevant sources found	Note in log, ask user for more context or alternative terms
Conflicting authoritative sources	Present both positions with evidence, recommend user decide
Topic is too broad	Ask user to narrow scope before researching
All sources are outdated	Note prominently, recommend user verify with official docs
Research reveals scope was wrong	Ask user if they want to pivot or continue