---
name: research
description: Governs how research is conducted — bounded agent spawning, no recursive sub-agents, web content downloaded as markdown and scanned locally. Use whenever launching research agents, fetching web content for analysis, or when another skill (like research-tree) is about to spawn agents that touch the web. Composes with workpad for output placement and research-tree for multi-topic structure.
---

# Research Governance

This skill regulates **how** research agents behave. It does not replace research-tree (which governs the **structure** of multi-topic research) or workpad (which governs **where** output goes). It layers on top of both.

## The core problem this solves

Without governance, a research agent can spawn sub-agents, which spawn more sub-agents, which each scrape entire websites. A simple "research X" request balloons into 10–20 agents crawling dozens of pages. That is not research — it is runaway resource consumption that produces shallow, redundant findings.

## The rules

### 1. Research agents must not spawn sub-agents

Every agent dispatched for research work is a **leaf agent**. It does its own reading, searching, and fetching. It does not delegate to further agents.

#### Agent tiers

Pick the right agent for the job. All three are tool-restricted and cannot spawn sub-agents:

| Agent | Model | Can write files | Web fetch cap | Use for |
|-------|-------|----------------|---------------|---------|
| `scout` | haiku | No | 2 pages | Quick fact extraction — a version number, a function signature, a config value from a web page |
| `search` | sonnet | No | 3–5 pages | Code/file lookups, symbol tracing, "where is X defined", multi-file search |
| `researcher` | opus (medium effort) | Yes | 5 pages | Deep topics requiring synthesis and a written report — architecture comparisons, technology evaluations, multi-source analysis |

**Default to `scout`** for simple lookups. **Use `search`** when you need to trace through code. **Use `researcher`** only when the topic genuinely needs synthesis and a written document.

When spawning research agents (via the Agent tool or workflow scripts):

- Use `subagent_type: "scout"` for quick fact extraction from a page or file
- Use `subagent_type: "search"` for code/file lookups and symbol tracing
- Use `subagent_type: "researcher"` for complex topics that need a written report
- In workflow scripts, use `agentType: 'scout'`, `'search'`, or `'researcher'` accordingly

The **orchestrator** (you, the main agent, or the workflow script) is the only entity that decides how many agents run. Individual research agents never make that decision.

### 2. Web content is fetched and read, not scraped

When research requires information from the web:

- **Fetch specific pages.** Use `WebFetch` to download a specific URL. The tool returns the page content as text/markdown.
- **Read the content locally.** Extract what you need from the fetched content. Do not follow every link.
- **Budget fetches per agent.** A single research agent should fetch at most 3–5 pages. If the research genuinely needs more, that is a sign the topic should be split into multiple agents at the orchestrator level — not that one agent should crawl more.
- **Never crawl.** Do not write loops that follow links, do not fetch "all pages" from a documentation site, do not spider a domain.

#### How to fetch web content

**Built-in tools (always available):**
- `WebFetch` — fetches a URL and returns content. Works for most documentation pages, blog posts, API references.
- `WebSearch` — searches the web and returns results with snippets. Use to find the right URL before fetching.

**MCP servers for richer web-to-markdown conversion (if configured):**
- `@anthropic/fetch` — Anthropic's fetch MCP; similar to WebFetch but runs as an MCP server
- `firecrawl` — converts web pages to clean markdown; good for documentation sites
- `markdownify` / `reader` — HTML-to-markdown conversion services
- `jina-reader` — extracts main content from web pages as markdown
- `browser-tools` — browser automation for pages that require JavaScript rendering

Check what MCP servers are available with `ToolSearch` before falling back to raw `WebFetch`. If a markdown-conversion MCP is available, prefer it — the output is cleaner and easier to scan.

**The pattern for web research:**
```
1. WebSearch to find relevant URLs (1-3 searches)
2. WebFetch (or MCP equivalent) to download 1-3 most relevant pages
3. Read the downloaded content, extract findings
4. Write findings to report file
```

This is **one agent's** entire web interaction. Not ten agents each doing this.

### 3. The orchestrator controls breadth, agents control depth

The division of responsibility:

| Concern | Who decides |
|---------|-------------|
| How many agents to spawn | Orchestrator (you) |
| Which topics to research | Orchestrator, informed by research-tree |
| How deep to go on one topic | The individual agent |
| Whether to fetch a web page | The individual agent |
| Whether to spawn another agent | **Never the individual agent** |
| Where to write output | Workpad skill |

### 4. Phases gate runaway growth

When using research-tree's phased approach:

- **Review each phase's output before launching the next.** This is not optional — it is the checkpoint where you catch redundancy, contradiction, or scope creep.
- **Trim the next phase** if earlier phases already answered some questions. Don't launch agents for topics that are already covered.
- **Cap total agents.** A typical research tree should use 3–12 agents total across all phases. If you're planning more than 15, the decomposition is too fine-grained — consolidate topics.

### 5. Research output goes to the workpad

Compose with the workpad skill:

- Individual agent reports → `research/<dated-subfolder>/phase-N-<topic>.md`
- Summary/index → `research/<dated-subfolder>/index.md`
- If no workpad exists, ask the user before creating one

## Applying this skill

When you are about to do research — whether triggered by the user saying "research", "investigate", "look into", or by another skill like research-tree — apply these rules:

1. **Plan first.** List the topics and how many agents you need. Share with the user.
2. **Instruct each agent.** Every agent prompt must include: the specific research question, where to write output, and the constraint that it must not spawn sub-agents.
3. **Use the search agent for lookups.** For "find where X is defined" or "what files reference Y", use `subagent_type: "search"` — it is tool-restricted and cannot spawn agents by design.
4. **Fetch web content through the agent, not through sub-agents.** The agent doing the research fetches the pages it needs directly.
5. **Review between phases.** Read what came back before sending more agents.

## What this skill does NOT govern

- The internal structure of a research tree (phases, dependencies) — that's research-tree
- Where files go — that's workpad
- Whether to do research at all — that's your judgment as orchestrator
- Which model to use — out of scope