---
name: checkpoint-research
description: Run multi-step research tasks with checkpoint tracking. Saves progress to an MD file after each step so work survives timeouts and can be resumed. Use for competitive analyses, multi-source investigations, or any research with 3+ sequential steps.
version: 1.0.0
author: case
metadata:
  openclaw:
    emoji: "📋"
    category: "research"
tags:
  - research
  - checkpoint
  - resumable
  - analysis
---

# Checkpoint Research

Run multi-step research with automatic progress tracking. If you time out, the next run picks up where you left off.

## When to Use

- Competitive analyses (multiple competitors to research)
- Multi-source investigations (several URLs/topics to cover)
- Any research task with 3+ sequential items that might timeout

## How It Works

1. Create a progress file at the specified path
2. Before each step, read the progress file to check what's done
3. Skip completed steps (marked `[x]`)
4. After completing each step, write findings to the file and mark `[x]`
5. If timed out mid-run, next invocation reads file and continues

## Usage

When given a research task, structure it as follows:

### 1. Initialize Progress File

```markdown
# [Research Title] — Progress

## Status: IN PROGRESS

## Steps
- [ ] 1. [Item name]
- [ ] 2. [Item name]
- [ ] 3. [Item name]

## Final Sections
- [ ] Summary / Verdict
- [ ] Recommendations

## Findings

*(Written below as each step completes)*
```

Save to: `data/investigations/[topic]-progress.md`

### 2. Research Loop

```
For each unchecked item:
  1. Read progress file
  2. Find first unchecked `- [ ]` item
  3. Research it (web_search, web_fetch, etc.)
  4. Append findings under ## Findings with a ### heading
  5. Mark the item `[x]` in the checklist
  6. Write updated file to disk immediately
  7. Continue to next item
```

### 3. Completion

When all items are `[x]`:
1. Write final sections (summary, recommendations)
2. Change `## Status: IN PROGRESS` to `## Status: COMPLETE`
3. Deliver the full report

## Template for Spawning

When spawning a sub-agent with checkpoint research:

```
Read the progress file at [PATH] first.
If any items are marked [x], skip them — continue from the first unchecked item.
After researching each item, IMMEDIATELY write your findings to the file and mark it [x].
When all items are complete, write the final sections and mark status as COMPLETE.
```

## Cost Impact

~2-3K extra tokens per full run vs non-checkpoint approach.
Saves 20-30K+ tokens on any timeout (avoids full re-run).
Net positive whenever timeout risk exists (tasks with 5+ web fetches).

## Progress File Location

Default: `/home/wdjones/.openclaw/workspace/data/investigations/[topic]-progress.md`