> ## Documentation Index
> Fetch the complete documentation index at: https://rapidreview.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Running research with Merv

> The operating loop from the human's side: what to ask for at each stage, and what the agent does with it.

You direct; the agent operates the workflow over MCP; the brain enforces the gates. State machine: [Experiments and reviews](/docs/merv/concepts/experiments-and-reviews).

## The loop

Whatever the stage, the agent's move is the same:

<Steps>
  <Step title="Read state">`workflow.status_and_next(project_id, experiment_id?)` — gates, allowed actions, missing evidence, `next_action`.</Step>
  <Step title="Do that work">Locally, in a sandbox, or through the specialist skill it names.</Step>
  <Step title="Submit through MCP">Plans, results, reports, graphs are real only once submitted and uploaded.</Step>
  <Step title="Read state again">After every transition or review.</Step>
</Steps>

The skills installed with the plugin teach this loop. You say what to test and answer questions.

## Stage by stage

| Stage              | You say                                                         | The agent does                                                                                                                                                                                                                                                                            |
| ------------------ | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Plan**           | The claim to test and the constraints (data, compute, deadline) | `experiment.create` → `experiments/<name>/`; writes `plan.md` from the template: hypothesis, method, comparison, **decision rule and threshold before running**, invalidation conditions. Cites prior `exp_…` ids and papers in portable form (`arXiv:…`, DOI, URL) only when they matter |
| **Design review**  | "Request a design review"                                       | `review.request` → hands the prompt to a separate reviewer (see [Reviewer handoff](/docs/merv/clients/reviewer-handoff)). Rejection is normal; revise, resubmit, re-request                                                                                                                    |
| **Execute**        | "Run it" — or "in a sandbox" for heavy work                     | Everything stays in the experiment folder. **All** seeds and configs kept, failed ones included. No automatic sync between checkout, sandbox, and Merv — outputs are pulled in before submission                                                                                          |
| **Submit results** | "Write the report and graph and submit"                         | `report.md` interprets results **against the decision rule** and stays inside the tested scope; `graph.json` is the reasoning path, ≤ 16 nodes, hand-authored. `artifact.submit` per file, every upload command run. Edited after submitting? Resubmit                                    |
| **Results review** | "Request an experiment review"                                  | Same handoff, `experiment-attempt-review` skill. Outcomes: pass · back to execution · back to planning                                                                                                                                                                                    |
| **Complete**       | "Complete it"                                                   | Only through MCP, only when the gates hold. A rejection is followed, never worked around                                                                                                                                                                                                  |

Push for the smallest experiment that gives a decision-relevant signal; the plan should say why that scope is enough.

## Beyond one experiment

* **Champion**: on projects with an objective, the manager agent nominates promising output with `candidate.submit` as soon as it appears, compares with `candidate.list`, promotes with `candidate.promote` and a reason. Files → Artifacts or Object Storage, never Git.
* **Reflection**: after several experiments, `workflow.status_and_next` suggests, then requires, a wave — ask for it and the `project-reflection` skill runs roster → lenses → synthesis → review → publish. Thresholds: [Reflection waves](/docs/merv/concepts/reflection-waves).
* **Feed**: findings, kills, numbers that moved, papers, dead ends — the agent posts as it goes so the project reads without opening artifacts. [The Feed](/docs/merv/concepts/feed).