> ## 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.

# Experiments and reviews

> The experiment state machine, its five gates, and how an independent reviewer is brought in and kept independent.

## States

```mermaid theme={"theme":{"light":"github-light","dark":"dark-plus"}}
stateDiagram-v2
    direction TB
    [*] --> planned
    planned --> design_review: plan
    design_review --> planned: needs changes
    design_review --> ready_to_run: pass
    ready_to_run --> running
    running --> running: retry_running
    running --> experiment_review: results
    experiment_review --> running: fix run or report
    experiment_review --> planned: new attempt
    experiment_review --> complete: pass
    complete --> [*]
```

`failed` and `abandoned` are explicit terminal exits from any live state.

`workflow.status_and_next` is the agent's read of the current state, its gates, the allowed actions, and the next action. Agents call it first and after every transition.

## Gates

An experiment moves forward only when the gate has real evidence behind it:

| # | Gate                   | Satisfied by                                                                                                      |
| - | ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
| 1 | **Plan**               | A submitted, size-bounded plan with the required sections                                                         |
| 2 | **Design review**      | A passing independent review pinned to that exact plan                                                            |
| 3 | **Execution evidence** | Result artifacts from the current attempt                                                                         |
| 4 | **Report and graph**   | A valid report plus an authored DAG-shaped logic graph; if a metrics exhibit exists, the report must interpret it |
| 5 | **Experiment review**  | A passing independent review of the exact submitted attempt snapshot                                              |

Transitions seal the artifact set in the same database transaction as the state change. Editing a file in your checkout changes nothing until you submit it again.

Limits: at most seven non-terminal experiments per project, and no new experiments while a project reflection is mandatory (see [Reflection waves](/docs/merv/concepts/reflection-waves)).

## Attempts

A rejection back to `planned` starts a **new attempt**; the old plan, evidence, and reviews stay on record. A rejection back to `running` keeps the attempt — the plan stands, the execution or the write-up doesn't.

## How a review happens

Four workflow roles: `design_reviewer`, `experiment_reviewer`, `reflection_reviewer`, `consolidation_reviewer` (`review.request` also accepts `human` and `automated_check` outside the gates).

1. The producer agent calls `review.request`.
2. The brain pins the target snapshot and returns a **short-lived capability** once, with a reviewer handoff prompt.
3. A **distinct** reviewer session calls `review.start` and receives the pinned evidence plus bounded context — not the producer's conversation.
4. The reviewer submits one verdict and synopsis through `review.submit`.
5. Submission re-checks that the request and snapshot are still current before it routes a rejection or satisfies a gate.

Capabilities are stored as hashes and expire after an hour; re-requesting reissues one. Producer and reviewer session ids must differ — a workflow guarantee, not cryptographic proof. Per client: [Reviewer handoff](/docs/merv/clients/reviewer-handoff).

## What reviewers look for

* **Design review**: can this plan actually test its claim? Is the success criterion decided before the run? Is the scope bounded?
* **Experiment review**: does the evidence support the conclusion? Was the approved plan followed? Does the report interpret the metrics it shows? Is the logic graph honest?

Reviewers are told to be adversarial. A rejection with a reason is the normal case, not a failure.