Research

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:

1. Create a kebab-case folder for the topic (e.g. oauth-token-refresh/)
2. Create summary.md immediately. This is the living document. Update it as you go, not at the end.
3. 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?