Deep ResearchSAFE

Open-source autoresearch powered by autonomous coding agents. Run Claude Code, OpenCode, and Codex with grading, shared knowledge, and multi-agent evolution. Accepted at COLM 2026.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

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

```markdown
# 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,

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.