# Research

> 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.

- Skill: `jessedegans/research` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jessedegans/research`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jessedegans/research/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: jessedegans (https://skillmd.com/u/jessedegans)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jessedegans/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?