| name | research |
| description | Use when the user asks a research question, wants to explore a topic, compare options, or needs to investigate something before making a decision. Sets up a structured research folder with living documents and uses sub-agents for parallel exploration. Use when: user says "research X", "look into Y", "compare A vs B", "what are our options for", "investigate", "explore", or asks a question that needs multiple sources to answer well.
|
| version | 1.0.0 |
Research
The Rule
Write things down as you go. Chat history is not memory. After 20+ turns you won't remember turn 3. The file system is your working memory.
Setup
When a research topic arrives:
- Create a kebab-case folder for the topic (e.g.
oauth-token-refresh/)
- Create
summary.md immediately. This is the living document. Update it as you go, not at the end.
- Ask the user for depth:
- Quick - a few searches, one file with the answer
- Standard - multiple sources, structured summary, key findings (default)
- Deep dive - comprehensive exploration, comparisons, trade-off analysis
The File System
| File | Purpose |
|---|
summary.md | Living synthesis. Always exists, always current. Lead with the answer. |
notes.md | Raw findings, quotes, data points. Write as you discover, not at the end. |
sources.md | URLs with one-line annotations. Every claim should be traceable. |
scratch.md | Hypotheses, open questions, thinking out loud. |
comparison.md | Side-by-side analysis when comparing options. |
Keep it flat. No build system, no subdirectories, just markdown.
The Loop
GATHER CONTEXT -> SYNTHESIZE -> VERIFY -> REPEAT
Gather
- Preview large sources before loading them. Filter before reading.
- Save relevant quotes and data points to
notes.md as you find them.
- Log every URL to
sources.md with a one-line annotation.
Synthesize
- Update
summary.md after each significant finding, not at the end.
- If context gets confused: read the topic folder files to recover state. Don't replay the conversation.
Verify
- Are sources credible and recent? Do they agree or conflict?
- Does the synthesis actually answer the question?
- Are claims sourced? Are uncertainties called out explicitly?
Use the right tool level
| Need | Use |
|---|
| Specific lookup (one page, one fact) | Tools directly (WebFetch, Grep, Read) |
| Filter/parse/chain operations | Bash with pipes, save intermediates to files |
| 2+ independent questions in parallel | Sub-agents, each with a focused sub-question and a file path to save results to |
Sub-agent guidance
| Depth | Sub-agents |
|---|
| Quick | None. Just do it inline. |
| Standard | Optional. When 2+ independent threads exist. |
| Deep dive | Expected. Fan out, then synthesize their results. |
Each sub-agent gets: one specific sub-question, a file path to save results to (in the topic folder), and any relevant context (point to files, don't paste walls of text).
Writing Style
- Write like you're explaining to a smart colleague, not writing a textbook
- Lead with the answer or recommendation, then back it up
- Use tables for comparisons
- Include code snippets when they clarify faster than prose
- If something is uncertain or contested, say so explicitly
- End every
summary.md with a "So what?" section: what should we actually do with this?
