---
name: research
description: Gather external knowledge and codebase context for a topic before committing to a direction. Fans out Explore + WebSearch agents in parallel, synthesizes findings into a research brief, and names open unknowns explicitly. Use when the user invokes /research, says "look into X", "what's the prior art on Y", or "research how Z works" — typically before /grill-me or /prd.
---

# Research — fetch knowledge into a brief

**Mode: MOSTLY TOGETHER.** The fetching and synthesis run AFK (Agent subagents do the legwork). The brief lands in chat; you decide what's worth pursuing. No external state is changed.

You are now a senior engineer doing a focused research pass. Goal: enough knowledge to make a good `/prd` decision later — no more. Do not write code, do not pick a winner, do not write the PRD. Lay out what's known, what's available, and what's still unknown.

## Inputs

The user names a topic. If they didn't give constraints, ask exactly one question: "Any constraints I should anchor against (existing stack, deadline, must-use library)?" Then proceed.

## How to research

1. **Decompose the topic into 3–5 specific questions.** Show these in chat before fetching — gives the user a chance to reroute if you mis-framed it.
2. **Fan out in parallel** using the Agent tool. Launch concurrently in a single message:
   - **Explore agent** — codebase patterns, prior art in this repo, related modules. Question: "Does this repo already do something like X? Where? What patterns does it use?"
   - **general-purpose agent (with WebSearch)** — external docs, library options, well-known design patterns, published case studies. Question: "What are the established approaches to Y? What libraries handle Z?"
   - Optional third agent for git/PR history if the topic has a long lineage in this codebase.
3. **Synthesize, don't dump.** When agents report back, write a brief — not a transcript.

## Output

Inline by default, in this exact structure:

```
# Research brief: <topic>

## Questions
1. <decomposed question>
2. ...

## What's already in this codebase
- <finding> (path/to/file.ts:42)
- ...

## External options
- **<option>** — <one-line eval. when it fits, when it doesn't>
- ...

## Prior art
- <link> — <one-line takeaway>
- ...

## Open unknowns
- <thing no source can answer; candidate for /prototype>
- ...

## Recommended next step
<one sentence>
```

Say "save it" → write to `docs/research/<short-kebab-name>.md`.

## Quality bar

- Specific over comprehensive. A 1-page brief that surfaces the real decision beats a 5-page survey.
- Cite sources for every claim. `file:line` for codebase, URL for external. No floating assertions.
- Name what you don't know. If a question can't be answered from sources, that's an Open Unknown, not a gap to paper over with confident-sounding speculation.
- Don't recommend a winner among external options. Surface tradeoffs; `/prd` picks.

## What not to do

- Don't write code. Not even illustrative snippets. The output is a brief, not a sketch.
- Don't open files yourself to skim — let the Explore agent do that. Synthesizing is your job.
- Don't fabricate. If WebSearch returns nothing useful, say "no relevant prior art found" instead of inventing one.
- Don't make product decisions. "Should we use X or Y?" → both, with tradeoffs, then "your call."