# review-plan

> Have a second model review a plan before any code is written, then accept, dispute or escalate each issue until the reviewer approves or you decide.

`review-plan` sends a plan file to the reviewer model (Codex CLI by default). The reviewer checks whether the plan can reach its target: achievability, claims about the repository or libraries that do not hold, missing steps, logic flaws, and places where a standard solves the problem better. You then decide on each issue, edit the plan to fix the accepted ones, and repeat until the reviewer returns `APPROVE`.

The skill edits only the plan file. It does not implement code.

## When to use it

- After a plan is written, before implementation starts. This includes a `loop-plan` plan, which must be approved before `loop-implement` runs.
- For any plan file with headings, such as a design note or a plan written in plan mode.

## Invoke it

**Claude Code**

```text
/review-plan .cross-review/plans/move-tags-to-join-table-plan.md
```

**Codex**

```text
$review-plan .cross-review/plans/move-tags-to-join-table-plan.md
```

Without a path, the skill looks for a single `*-plan.md` in the repository and asks if it finds several or none. A plan outside the repository, such as a client’s plan-mode file, works when you give its path.

## What it works out by itself

- The plan path, the request it serves, and the decisions you made in the conversation. These go to the reviewer as the request and session context.
- Whether the plan is a `loop-plan` plan (it has a `Plan schema` section naming `loop-plan/v1`). If so, the reviewer also checks the plan contract: binary criteria, end-to-end scenario, retry or rollback for risky steps, and checkpoints.
- The review settings for the reviewer’s model and effort, from your dashboard settings, unless you name one. See [Settings](https://cross-review.tlelabs.com/docs/guides/settings/).

## Round by round

1. **Start.** The skill starts a session with `review_begin` and passes the plan path, the request and the session context. The session is stored under `.cross-review/sessions/`.

2. **Wait.** It calls `review_wait` until the reviewer finishes its round, and reports what the reviewer is doing (for example, reading a file), not just “running”.

3. **Classify each issue.** The reviewer returns numbered issues (`ISSUE-N`) with category, severity, plan section, problem, evidence and a suggested fix. The skill decides each one, in this order of authority: your latest decision, the original request and target, verified repository facts, the plan, then the reviewer.

   - **ACCEPT**: a real problem. The plan is edited to fix the root cause, and the fix is checked against the target and the fixed decisions.
   - **DISPUTE**: the issue is a style preference, optional polish, speculative infrastructure, or a request for a limit that names no resource at risk. The skill states the evidence.
   - **plan-gap**: the plan itself causes a bug or a real risk, or an option outside the plan clearly beats it. It is put to you as a proposal with cost, risk and a recommendation. Nothing changes until you agree.
   - **USER DECISION**: the fix would change user-visible behavior, scope, an interface, persistence, compatibility, dependencies, or architecture. The other fixes are finished first, then each decision is asked one at a time.

4. **Reply.** It calls `review_reply` with `FIXED_ITEMS` (one line per issue with where it was fixed) and `DISPUTED_ITEMS` (one line per disputed issue with its evidence, or `None — all issues addressed`). The reviewer checks again and may raise new issues. There is no round limit.

5. **End.** When the reviewer returns `APPROVE`, the session is finished with `review_end`. For a `loop-plan` plan, the `Plan Review` line becomes `APPROVE (review-plan <session id>, <date>)`.

When the same disagreement repeats, or the reviewer reports a stalemate, the skill shows the deadlocked issues and asks you to decide.

> **Note:**
>
> A stopped round (error, stall or timeout) is not a finished review. The session can continue with the same reviewer thread once you ask. See [Troubleshooting](https://cross-review.tlelabs.com/docs/guides/troubleshooting/).

## What you can say in chat

| You say                            | Effect                                                                         |
| ---------------------------------- | ------------------------------------------------------------------------------ |
| “Use model X” or “effort high”     | The model or effort is passed to the reviewer, and remembered for later rounds |
| “Skip the review”                  | The review stops, and the record shows that you skipped it                     |
| “Stop”                             | The session stops; you can resume it later                                     |
| “Accept it as approved”            | The plan is recorded as approved by you, not by the reviewer                   |
| A decision on a USER DECISION item | The skill applies that decision, and no other                                  |

## Example

Project: atlas-notes. The plan `move-tags-to-join-table-plan.md` is reviewed.

- Round 1: the reviewer raises ISSUE-1, the migration step drops the old column before the backfill has run (severity high). The skill accepts it and moves the backfill ahead of the drop. ISSUE-2 asks for a cache of tag names. The skill disputes it: the request does not mention lookup speed, and the plan has no measurement that shows a need.
- Round 2: the reviewer accepts the disputed point and raises ISSUE-3, a missing rollback path for the migration. The skill accepts it and adds the path to phase 1.
- Round 3: `APPROVE`. The session ends, and `Plan Review` reads `APPROVE (review-plan <session id>, <date>)`.

See [loop-plan](https://cross-review.tlelabs.com/docs/skills/loop-plan/) for writing the plan, and [loop-implement](https://cross-review.tlelabs.com/docs/skills/loop-implement/) for carrying it out.