research-web

What this skill does

**Research request**: $ARGUMENTS

# Thoroughness Level

**FIRST**: Determine thoroughness before researching. Parse from natural language or auto-select.

**Auto-selection logic**:
- Single fact/definition/date → quick
- Focused question about one topic → medium
- Comparison, evaluation, or "best" questions → thorough
- "comprehensive"/"all options"/"complete analysis"/"deep dive" → very-thorough

**Explicit user preference**: Honor user-specified level regardless of other triggers.

**Trigger conflicts (auto-selection only)**: Use highest level indicated.

| Level | Agents/Wave | Wave Policy | Behavior | Triggers |
|-------|-------------|-------------|----------|----------|
| **quick** | 1 | Single wave | Single web-researcher, no orchestration file, direct answer | "what is", "when did", factual lookups, definitions |
| **medium** | 1-2 | Single wave | Orchestration file, focused research on 1-2 angles | specific how-to, single technology, focused question |
| **thorough** | 2-4 | Continue while critical gaps remain | Full logging, parallel agents, cross-reference, follow-up waves | "compare", "best options", "evaluate", "pros and cons" |
| **very-thorough** | 4-6 | Continue until comprehensive OR diminishing returns | Multi-wave until all significant gaps addressed | "comprehensive", "complete analysis", "all alternatives", "deep dive" |

**Multi-wave**: For thorough/very-thorough, waves continue until satisficing criteria are met. No hard maximum — waves continue as long as productive and gaps remain.

**Agent count scaling**: Match agent count to genuine research facets, not perceived thoroughness. Each agent should have a distinct domain justifying dedicated research. Over-spawning wastes resources; under-spawning misses facets.

| Task Complexity | Agents | Rationale |
|----------------|--------|-----------|
| Simple fact-check | 1 | Single angle sufficient |
| Direct comparison (2-3 options) | 2-3 | One per option or dimension |
| Multi-facet evaluation | 3-5 | One per orthogonal facet |
| Comprehensive landscape | 5-7 | Cover all major dimensions |

**Ambiguous queries**: If thoroughness cannot be determined AND query is complex, ask:

```
I can research this at different depths:
- **medium**: Focused research on core aspects (~3-5 min)
- **thorough**: Multi-angle investigation with cross-referencing (~8-12 min)
- **very-thorough**: Comprehensive analysis covering all facets (~15-20 min)

Which level would you prefer?
```

State: `**Thoroughness**: [level] — [reason]` then proceed.

---

# Orchestration

Orchestrate parallel web researchers through iterative waves, then synthesize findings.

**Loop**: Determine thoroughness → Decompose → Launch Wave 1 → Collect → Cross-reference → Evaluate gaps → [If gaps + productive: next wave] → Synthesize → Output

**Orchestration file**: `/tmp/research-orchestration-{topic-slug}-{YYYYMMDD-HHMMSS}.md` — external memory for tracking multi-wave progress.

- **Topic-slug**: 2-4 key terms (nouns/adjectives), lowercase, hyphens. Exclude articles, prepositions, generic words.
- **Timestamp**: `YYYYMMDD-HHMMSS` via `date +%Y%m%d-%H%M%S`.

---

# Satisficing Criteria

## Wave Continuation

| Level | Continue When | Stop When (Satisficed) |
|-------|---------------|------------------------|
| quick | N/A | Always single wave |
| medium | N/A | Always single wave |
| thorough | Critical gaps remain AND previous wave productive AND ≤50% source overlap | No critical gaps OR diminishing returns OR >50% source overlap |
| very-thorough | Significant gaps remain AND previous wave productive AND ≤50% source overlap | No significant gaps OR diminishing returns OR >50% source overlap |

**Source overlap**: % of sources in current wave also cited in prior waves. >50% = cycling through same sources.

## Gap Classification

| Gap Type | Definition | Triggers New Wave? |
|----------|------------|-------------------|
| **Critical** | Core question unanswered, major conflict unresolved, key comparison missing | Yes (thorough, very-thorough) |
| **Significant** | Important facet unexplored, partial answer needs depth, newly discovered area | Yes (very-thorough only) |
| **Minor** | Nice-to-have detail, edge case, tangential | No — note in limitations |

## Satisficing Evaluation

**Definitions**:
- **Finding**: Distinct information answering part of the question, with source citation.
- **Substantive finding**: New information not already established in prior waves.
- **High-authority source**: Official docs, peer-reviewed research, established publications, recognized domain experts.
- **Independent sources**: Different underlying information origins. Two articles citing the same study = one source.
- **High confidence**: ≥3 independent sources OR ≥2 high-authority sources.
- **Medium confidence**: 2 independent sources OR 1 high-authority source.
- **Low confidence**: Single non-authoritative source, no corroboration.

**Satisficed when ANY true**:
- All critical gaps addressed (thorough) OR all significant gaps addressed (very-thorough)
- Diminishing returns: <2 new substantive findings AND no confidence increased AND no new areas
- User requested stopping
- All facets at medium+ confidence

**Continue when ALL true**:
- Gaps at triggering threshold (thorough: critical; very-thorough: significant)
- Previous wave productive (≥2 findings OR confidence improved OR new areas)
- ≤50% source overlap with prior waves

---

# Phase 1: Initial Setup (skip for quick)

## 1.1 Get timestamp & create todos

Run `date +%Y%m%d-%H%M%S` and `date '+%Y-%m-%d %H:%M:%S'`.

Todos = research areas + write-to-log operations. List grows during decomposition.

```
- [ ] Create orchestration file
- [ ] Topic decomposition→log
- [ ] (expand: research facets as decomposition reveals)
- [ ] Launch Wave 1 agents
- [ ] Collect Wave 1 findings→log
- [ ] Cross-reference→log
- [ ] Evaluate gaps→log
- [ ] (expand: Wave 2+ if continuing)
- [ ] Refresh: read full orchestration file
- [ ] Synthesize→final output
```

**Critical todos** (never skip): `→log` after each phase/agent; `Refresh:` before synthesis.

## 1.2 Create orchestration file

```markdown
# Web Research Orchestration: {topic}
Timestamp: {YYYYMMDD-HHMMSS}
Started: {YYYY-MM-DD HH:MM:SS}
Thoroughness: {level}
Wave Policy: {single wave | continue while critical gaps | continue until comprehensive}

## Research Question
{Clear statement}

## Topic Decomposition
(populated in Phase 2)

## Wave Tracking
| Wave | Agents | Focus | Status | New Findings | Decision |
|------|--------|-------|--------|--------------|----------|
| 1 | {count} | Initial investigation | Pending | - | - |

## Research Assignments
(populated in Phase 2)

## Collected Findings
(populated as agents return)

## Cross-Reference Analysis
(populated after each wave)

## Gap Evaluation
(populated after each wave)

## Synthesis Notes
(populated in final phase)
```

# Phase 2: Topic Decomposition & Agent Assignment

## 2.1 Decompose into ORTHOGONAL facets

Analyze the query to identify **non-overlapping** research angles. Each agent gets a distinct domain with clear boundaries.

1. **Core question**: What is fundamentally being asked?
2. **Facets**: What distinct aspects need investigation? (technical, comparison, practical, current state, limitations)
3. **Orthogonality check**: Each facet covers a distinct domain. No two facets would naturally run the same queries. Boundaries are explicitly statable.

**Bad** (overlapping): Agent 1 = "Research Firebase", Agent 2 = "Research real-time databases"
**Good** (orthogonal): Agent 1 = "Firebase — features, pricing, limits", Agent 2 = "Non-Firebase alternatives: Supabase, Convex, PlanetScale"

**Orthogonality strategies**: by entity, by dimension, by time horizon, by perspective.

## 2.2 Plan agent assignments with explicit boundaries

| Facet | Research Focus | Explicitly EXCLUDE |
|-------|----------------|-------------------|
| {facet 1} | "{scope}" | "{what others cover}" |
| {facet 2} |