Research Skill

# Research Skill

## Description
Conduct open-ended research on a topic, building a living markdown document. The conversation is ephemeral; the document is what matters.

## Trigger
Activate when the user wants to:
- Research a topic, idea, or question
- Explore something before committing to building it
- Investigate options, patterns, or approaches
- Create a "research doc" or "investigation"
- Run deep async research on a complex topic

## Research Directory
Each research topic gets its own folder:
```
~/.openclaw/workspace/research/<topic-slug>/
├── prompt.md          # Original research question/prompt
├── research.md        # Main findings (Parallel output or interactive notes)
├── research.pdf       # PDF export (when generated)
└── ...                # Any other related files (data, images, etc.)
```

---

## Two Research Modes

### 1. Interactive Research (default)
For topics you explore together in conversation. You search, synthesize, and update the doc in real-time.

### 2. Deep Research (async)
For complex topics that need comprehensive investigation. Uses the Parallel AI API via `parallel-research` CLI. Takes minutes to hours, returns detailed markdown reports.

**When to use deep research:**
- Market analysis, competitive landscape
- Technical deep-dives requiring extensive source gathering
- Multi-faceted questions that benefit from parallel exploration
- When user says "deep research" or wants comprehensive coverage

---

## Interactive Research Workflow

### 1. Initialize Research

1. **Create the research folder** at `~/.openclaw/workspace/research/<topic-slug>/`

2. **Create prompt.md** with the original question:
   ```markdown
   # <Topic Title>

   > <The core question or curiosity>

   **Started:** <date>
   ```

3. **Create research.md** with the working structure:
   ```markdown
   # <Topic Title>

   **Status:** Active Research
   **Started:** <date>
   **Last Updated:** <date>

   ---

   ## Open Questions
   - <initial questions to explore>

   ## Findings
   <!-- Populated as we research -->

   ## Options / Approaches
   <!-- If comparing solutions -->

   ## Resources
   <!-- Links, references, sources -->

   ## Next Steps
   <!-- What to explore next, or "graduate to project" -->
   ```

4. **Confirm with user** - Show the folder was created and ask what to explore first.

### 2. Research Loop

For each exchange:

1. **Do the research** - Web search, fetch docs, explore code
2. **Update the document** - Add findings, move answered questions, add sources
3. **Show progress** - Note what was added (don't repeat everything)
4. **Prompt next direction** - End with a question or suggestion

**Key behaviors:**
- Update existing sections over creating new ones
- Use bullet points for findings; prose for summaries
- Note uncertainty ("seems like", "according to X", "unverified")
- Link to sources whenever possible

### 3. Synthesis Checkpoints

Every 5-10 exchanges, offer to:
- Write a "Current Understanding" summary
- Prune redundant findings
- Reorganize if unwieldy
- Check blind spots

### 4. Completion

When research is complete, update the status in `research.md`:

- **"Status: Complete"** — Done, stays in place as reference
- **"Status: Ongoing"** — Living doc, will be updated over time

**If the research is specifically for building a project:**
- Graduate to `~/specs/<project-name>.md` as a project spec
- Or create a project directly based on findings
- Update status to **"Status: Graduated → ~/specs/..."**

Most research is just research — it doesn't need to become a spec. Only graduate if you're actually building something from it.

---

## Deep Research Workflow

### 1. Start Deep Research

```bash
parallel-research create "Your research question" --processor ultra --wait
```

**Processor options:**
- `lite`, `base`, `core`, `pro`, `ultra` (default), `ultra2x`, `ultra4x`, `ultra8x`
- Add `-fast` suffix for speed over depth: `ultra-fast`, `pro-fast`, etc.

**Options:**
- `-w, --wait` — Wait for completion and show result
- `-p, --processor` — Choose processor tier
- `-j, --json` — Raw JSON output

### 2. Schedule Auto-Check (OpenClaw)

After creating a task, set up a cron job to check results and deliver them back to the user. Use `deleteAfterRun: true` so it cleans up automatically.

**⚠️ CRITICAL: Always calculate `atMs` correctly!**

```bash
# Get current timestamp in ms and add 15 minutes (900000 ms)
date +%s%3N  # Current time in epoch ms
# Example: 1770087600000 + 900000 = 1770088500000
```

**Always verify the scheduled time is in the future and has the correct year:**
```bash
date -d @$((1770088500000/1000))  # Should show a time ~15 min from now, correct year
```

```json
{
  "action": "add",
  "job": {
    "name": "Check research: <topic>",
    "schedule": {"kind": "at", "atMs": <VERIFY: must be current epoch ms + delay>},
    "sessionTarget": "isolated",
    "payload": {
      "kind": "agentTurn",
      "message": "Check research task <run_id>. Run: parallel-research result <run_id>. If complete, summarize key findings. If still running, reschedule another check in 10 min.",
      "deliver": true,
      "channel": "<source channel, e.g. telegram>",
      "to": "<source chat/topic, e.g. -1001234567890:topic:123>"
    },
    "deleteAfterRun": true
  }
}
```

**Key points:**
- Use the `cron` tool with `action: "add"`
- **ALWAYS verify `atMs` is correct** — run `date -d @$((atMs/1000))` to confirm year and time
- `atMs` should be ~10-15 min from now (ultra processor) or ~5 min (fast processors)
- `deleteAfterRun: true` removes the job after successful completion
- Deliver back to the same channel/topic that requested the research
- If still running, the cron job can create another check
- `PARALLEL_API_KEY` is available as env var — no need to inline it

### 3. Manual Check (if needed)

```bash
parallel-research status <run_id>
parallel-research result <run_id>
```

### 4. Save to Research Folder

Create the research folder and save results:
```
~/.openclaw/workspace/research/<topic-slug>/
├── prompt.md          # Original question + run metadata
├── research.md        # Full Parallel output
```

**prompt.md** should include:
```markdown
# <Topic Title>

> <Original research question>

**Run ID:** <run_id>
**Processor:** <processor>
**Started:** <date>
**Completed:** <date>
```

**research.md** contains the full Parallel output, plus any follow-up notes.

---

## PDF Export

Use the `export-pdf` script to convert research docs to PDF:

```bash
export-pdf ~/.openclaw/workspace/research/<topic-slug>/research.md
# Creates: ~/.openclaw/workspace/research/<topic-slug>/research.pdf
```

Or specify a custom output path:
```bash
export-pdf research.md ~/Desktop/output.pdf
```

**Note:** Tables render as stacked rows (PyMuPDF limitation). Acceptable for research docs.

---

## Commands

- **"new research: <topic>"** - Start interactive research doc
- **"deep research: <topic>"** - Start async deep research
- **"show doc"** / **"show research"** - Display current research file
- **"summarize"** - Synthesis checkpoint
- **"graduate"** - Move research to next phase
- **"archive"** - Mark as complete reference
- **"export pdf"** - Export to PDF
- **"check research"** - Check status of pending deep research tasks

---

## Document Principles

- **Atomic findings** - One insight per bullet
- **Link everything** - Sources, docs, repos
- **Capture context** - Why did we look at this?
- **Note confidence** - Use qualifiers when uncertain
- **Date important findings** - Especially for fast-moving topics

---

## Setup

See `SETUP.md` for first-time installation of:
- `parallel-research` CLI
- PDF export tools (pandoc, PyMuPDF)