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?
1---2name: research3description: 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.4---56# Research78## The Rule910**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.1112## Setup1314When a research topic arrives:15161. Create a kebab-case folder for the topic (e.g. `oauth-token-refresh/`)172. Create `summary.md` immediately. This is the living document. Update it as you go, not at the end.183. Ask the user for depth:19 - **Quick** - a few searches, one file with the answer20 - **Standard** - multiple sources, structured summary, key findings (default)21 - **Deep dive** - comprehensive exploration, comparisons, trade-off analysis2223## The File System2425| File | Purpose |26|------|---------|27| `summary.md` | Living synthesis. Always exists, always current. Lead with the answer. |28| `notes.md` | Raw findings, quotes, data points. Write as you discover, not at the end. |29| `sources.md` | URLs with one-line annotations. Every claim should be traceable. |30| `scratch.md` | Hypotheses, open questions, thinking out loud. |31| `comparison.md` | Side-by-side analysis when comparing options. |3233Keep it flat. No build system, no subdirectories, just markdown.3435## The Loop3637```38GATHER CONTEXT -> SYNTHESIZE -> VERIFY -> REPEAT39```4041### Gather4243- Preview large sources before loading them. Filter before reading.44- Save relevant quotes and data points to `notes.md` as you find them.45- Log every URL to `sources.md` with a one-line annotation.4647### Synthesize4849- Update `summary.md` after each significant finding, not at the end.50- If context gets confused: read the topic folder files to recover state. Don't replay the conversation.5152### Verify5354- Are sources credible and recent? Do they agree or conflict?55- Does the synthesis actually answer the question?56- Are claims sourced? Are uncertainties called out explicitly?5758## Use the right tool level5960| Need | Use |61|------|-----|62| Specific lookup (one page, one fact) | Tools directly (WebFetch, Grep, Read) |63| Filter/parse/chain operations | Bash with pipes, save intermediates to files |64| 2+ independent questions in parallel | Sub-agents, each with a focused sub-question and a file path to save results to |6566### Sub-agent guidance6768| Depth | Sub-agents |69|-------|-----------|70| Quick | None. Just do it inline. |71| Standard | Optional. When 2+ independent threads exist. |72| Deep dive | Expected. Fan out, then synthesize their results. |7374Each 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).7576## Writing Style7778- Write like you're explaining to a smart colleague, not writing a textbook79- Lead with the answer or recommendation, then back it up80- Use tables for comparisons81- Include code snippets when they clarify faster than prose82- If something is uncertain or contested, say so explicitly83- End every `summary.md` with a **"So what?"** section: what should we actually do with this?
jessedegans