researchclaw

---
name: researchclaw
description: Run the ResearchClaw autonomous research pipeline from ANY directory. 23-stage flow — literature review → hypothesis → experiment design → code generation/execution → result analysis → paper writing → peer review → final export. Use when the user asks to "research [topic]", "write a paper about [topic]", "investigate [topic]", run an autonomous research pipeline, or mentions "ResearchClaw".
---

# ResearchClaw — Autonomous Research Pipeline (global)

Turn any research idea into a full paper draft (with experiments + charts) via a 23-stage pipeline:
literature review → hypothesis generation → experiment design → code generation & execution → result analysis → paper writing → peer review → final export.

Project home: `$HOME/dev/AutoResearchClaw`

## How to invoke the CLI (PATH-independent)

The binary is symlinked at **`$HOME/.local/bin/researchclaw`** and resolves in any login shell.
To be safe regardless of how Claude was launched, prefer the explicit path:

```bash
RC="$HOME/.local/bin/researchclaw"      # or just `researchclaw` if ~/.local/bin is on PATH
```

## Config (reuse the shared, already-configured one)

A working config with the user's LLM key/model lives at:
`$HOME/dev/AutoResearchClaw/config.arc.yaml`

**Default invocation always passes it**, so the API key is reused and no per-directory setup is needed:

```bash
$RC run --config "$HOME/dev/AutoResearchClaw/config.arc.yaml" \
        --topic "Your research topic here" --auto-approve
```

### Per-project config (optional)
If the user wants a separate config in the current project instead:
```bash
$RC init                 # creates config.arc.yaml in cwd from the template
$EDITOR config.arc.yaml  # set llm.base_url + llm.api_key (or api_key_env)
$RC run --topic "..." --auto-approve
```

## `run` options
- `--topic` / `-t`        research topic (overrides config)
- `--config` / `-c`       config file (default `config.yaml`; we default to the shared `config.arc.yaml`)
- `--output` / `-o`       output dir (default `artifacts/rc-YYYYMMDD-HHMMSS-HASH/`)
- `--from-stage`          resume from a stage, e.g. `PAPER_OUTLINE`
- `--auto-approve`        auto-approve gate stages (5, 9, 20) without human input

## Other subcommands
`run` · `validate` · `doctor` · `init` · `info` · `report` · `serve` · `dashboard` · `wizard` · `project` · `mcp` · `overleaf` · `trends` · `profile` · `skills` · `calendar` · `attach` · `status` · `approve` · `reject` · `guide`

- `validate` — validate a config file
- `doctor`   — environment & config health check (note: probes the LLM endpoint over the network)
- `info`     — show resolved config: profile, prompt bank, stage list, extras

## Experiment modes (`experiment.mode` in config)
| mode | description |
|------|-------------|
| `simulated`  | LLM generates synthetic results (no code execution) |
| `sandbox`    | execute generated code locally via subprocess |
| `ssh_remote` | execute on a remote GPU server via SSH |

## Output structure (after a successful run)
```
artifacts/<run-id>/
├── stage-1/ .. stage-10/ (stage-10/experiment.py = generated experiment code)
├── stage-12/runs/run-1.json          # experiment execution results
├── stage-14/{experiment_summary.json, results_table.tex}
├── stage-17/paper_draft.md           # full paper draft
├── stage-22/charts/*.png             # generated visualizations
└── pipeline_summary.json             # overall pipeline status
```

## Troubleshooting
- **Config validation error** → `$RC validate --config <cfg>`
- **LLM connection failure** → check `llm.base_url` and the API key in the config (or `llm.api_key_env`)
- **Sandbox execution failure** → ensure `experiment.sandbox.python_path` exists and has numpy
- **Gate rejection** → use `--auto-approve`, or manually approve at stages 5 / 9 / 20
- **`command not found: researchclaw`** → use the explicit `$HOME/.local/bin/researchclaw`; or ensure `~/.local/bin` is on PATH (it is, via `~/.bash_profile`)

## Maintenance
- The CLI is a symlink to the project venv. If `$HOME/dev/AutoResearchClaw` is moved/reinstalled, recreate it:
  `ln -sfh "$HOME/dev/AutoResearchClaw/.venv/bin/researchclaw" "$HOME/.local/bin/researchclaw"`
- This global skill is a config-aware wrapper; the original project-scoped skill lives at
  `$HOME/dev/AutoResearchClaw/.claude/skills/researchclaw/SKILL.md` and takes precedence when Claude runs inside that project.