> ## 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.
# Reflection waves
> How a project steps back: five lenses over one snapshot, a reviewed synthesis, and an atomic publish into the next phase.
A reflection wave is the project-level workflow. It runs over a snapshot of every terminal experiment and every claim's current status, and it ends by publishing a new project graph, approved claim changes, and the next wave of experiments.
## States
```mermaid theme={"theme":{"light":"github-light","dark":"dark-plus"}}
stateDiagram-v2
direction TB
[*] --> reflecting
reflecting --> synthesizing: 5 lens docs
synthesizing --> reflection_review: graph, doc, change spec
reflection_review --> synthesizing: return, keep lenses
reflection_review --> reflecting: return, new attempt
reflection_review --> consolidating: pass
consolidating --> published: proposal reviewed
published --> [*]
```
`abandoned` is the explicit terminal exit. One wave may be open per project at a time.
## Gates
| # | Gate | Satisfied by |
| - | --------------------- | -------------------------------------------------------------------------------------------------------- |
| 1 | **Roster** | Exactly five lenses: `amplify`, `avoid`, `entropy`, plus two wave-specific lenses with distinct charters |
| 2 | **Lens coverage** | One current-attempt lens document per lens |
| 3 | **Synthesis** | A project graph, a concise reflection document, and a materializable claim/experiment change spec |
| 4 | **Reflection review** | A passing independent review pinned to that exact synthesis |
## Lenses
Three are fixed — `amplify` (what's working, push it), `avoid` (what's failing, stop it), `entropy` (what hasn't been tried) — and two are written for the wave with distinct charters. Each reads the snapshot independently; none sees another's findings until synthesis. `reflection.create` opens the wave.
## Consolidation and publish
Passing reflection review makes the research decision authoritative and starts **code consolidation**: one immutable proposal must account for every experiment, and a separate `consolidation_reviewer` checks it. The runner then compare-and-swaps that exact proposal into Merv's central Git ref. Only after that receipt does publish happen, atomically: record the graph version, apply approved claim changes, create the approved experiment wave, record the event.
## When a wave is triggered
The project has no status column of its own; its state is derived:
| Signal | Effect |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| An open reflection exists | It takes priority in project-level guidance |
| 3 newly terminal experiments, or a claim becomes contradicted | Reflection **suggested** |
| Project idle with at least one newly terminal experiment | Reflection **recommended** |
| 5 newly terminal experiments | A published reflection is **required** before another experiment can be created |
Experiment-scoped status calls stay focused on that experiment and carry the project's reflection signal alongside.
Running one: [Running research → Reflection wave](/docs/merv/guides/running-research#run-a-reflection-wave).