/deep-research

name: deep-research
description: "Research the problem domain before coding. Web search for techniques, save raw sources, write structured findings, update the index."

Deep Research

Research the problem thoroughly before writing code. Understand what's known, what's been tried, and what approaches exist.

When to Use

• Starting a new task or problem
• Stuck after multiple evals without improvement
• Pivoting to a fundamentally different approach
• The problem involves domain-specific knowledge you're unfamiliar with

Notes Directory Structure

notes/
├── index.md              ← table of contents for research/ and experiments/
├── raw/                  ← saved web pages, paper excerpts (immutable, never edit)
├── research/             ← your synthesized findings (link back to raw/)
│   └── _coverage.md      ← the research coverage ledger (dimensions × covered/partial/missing)
└── experiments/          ← eval reflections and results (written by reflect heartbeat)

Process

1. Understand the Problem — and Map the Research Space

Read the task description and key files. Identify what's being optimized, what the constraints are, and what makes it hard. Check `coral log` and `{shared_dir}/notes/` for prior work.

Then **decompose the problem into 4–8 research dimensions** — the distinct things a team would need to understand to win *this* task. Derive them from the task, don't pull them from a fixed list. Useful starting prompts (not a required set): *prior art / SOTA methods*, *mechanism or theory*, *implementation / libraries*, *the evaluation & grader surface*, *failure modes*, *adjacent fields*. Drop the ones that don't apply; add task-specific ones that do.

Record them in the **coverage ledger** at `{shared_dir}/notes/research/_coverage.md` — the team's map of what's been researched and what hasn't. If it doesn't exist, create it with every dimension `missing`; if it does, read it first and target the gaps rather than re-covering what's done:

# Research Coverage — <task name>
<!-- Owned by the research team. Update on every research pass. Dimensions are
     derived from THIS task, not a fixed list. Status: covered | partial | missing -->

| Dimension (what to understand)  | Status  | Note                                | Last touched |
|---------------------------------|---------|-------------------------------------|--------------|
| Prior art / SOTA methods        | missing | —                                   | —            |
| Failure modes of approach X     | missing | —                                   | —            |
| Evaluation surface / grader     | missing | —                                   | —            |

This ledger is what turns re-research into gap-targeting: every pass below updates one or more rows instead of duplicating work. `_coverage.md` is a team meta-file (the `_` prefix keeps the index/link tooling from treating it as a note) — one per task, updated in place, never forked.

2. Search — Cast a Wide Net, Then Focus

**Broad survey** — search for the problem class:

• `"[problem domain] state of the art methods"`
• `"[problem domain] survey paper"`
• `"[problem domain] benchmark comparison"`

**Specific techniques** — once you identify promising approaches:

• `"[technique name] vs [alternative] comparison"`
• `"[technique name] implementation details"`
• `"[technique name] python library"`

**Practical implementations** — find code and libraries:

• `"[problem] python implementation github"`
• `"[problem] open source solution"`

Do 3-5 focused searches. When reading papers and articles, focus on methodology and results tables — how did they solve it, and what performance did they achieve?

**Then take one hop out.** From your two or three best sources, follow the citation graph one step in each direction: the works they *cite* (backward — this surfaces the seminal paper the field builds on) and the works that *cite them* (forward — this surfaces the recent work that extends or contests them). Neither reliably shows up in a keyword sweep. Use `WebFetch` on a paper's reference list or its Semantic Scholar / Google Scholar "cited by" page, and fold anything new and on-topic into your set before you start writing.

3. Save Raw Sources — Retrieve First, Then Write

**The hard rule: a claim you can't point to a saved source for is a claim, not a finding.** Retrieve the source *before* you write the note that leans on it — even when you know the answer cold, fetching the actual page is a few seconds and it's the difference between a citation and a memory of a citation. Never write a number, a benchmark result, or a "X beats Y" into a research note that isn't backed by a file in `raw/`. The grounding check in step 6 enforces this mechanically.

For every useful source, save the raw content so it can be verified later:

{shared_dir}/notes/raw/source-name.md

Use `WebFetch` to get the full page, then write it to `notes/raw/`. These are immutable — never edit raw sources, only reference them from research notes.

When the source is **not a plain web article** (paper PDF, GitHub repo, video, conference talk, internal docs, chat log…), see [`references/source-types.md`](references/source-types.md) for capture procedure, what to extract, and the right frontmatter fields per type. Generic `WebFetch` only handles ~half of real research inputs cleanly.

When `WebFetch` fails, sources contradict, search returns nothing useful, or you find an existing-but-stale note covering your topic, see [`references/failure-modes.md`](references/failure-modes.md) for diagnosis and recovery procedures.

4. Compare Approaches

Identify 2-4 candidate approaches. For each, document:

• **What it is** — one-sentence description
• **Why it might work** — connection to the problem structure
• **Known limitations** — when it fails or scales poorly
• **Estimated complexity** — how hard is it to implement?
• **Evidence** — papers, b