Reviews

A review is an independent check of a branch. A fresh agent, which has not seen the plan, reads the diff and writes findings. You decide on each finding, and the ones you keep become a fix plan or comments on the merge request.

Each review is a file in your project's .invariant/reviews folder, one per branch. It is local state: it is never committed. A review is driven by a review session, which you hand to an agent with one pasted line, like any session.

The reviews list

Open Reviews from the rail, or press g r. Each review is one row:

• Ref and Review: the review session's ref and the branch under review.
• Stage: where the newest round stands. See Review stages.
• Triage: how many findings still need your decision.
• Harness: the agent that writes the review.
• Work under review: the session whose work is reviewed, or a note that the review covers a branch on its own.
• Rounds and Updated.

In an organisation project, the list also shows the Assignee and the People who took part. A review that an agent is still writing shows its stage, and for a Fleet review how many gates have reported.

With no review yet, the page explains the two ways in: Request review on a finished session, or Review a branch.

Review stages

Request a review

There are two ways to start one.

For a finished session

When a session is Done, its What next card offers two buttons:

• Simple review (v): one reviewer covers the whole change.
• Fleet review (⇧V): the project's gates, each reviewing in its own context. It is greyed until a gate is enabled; Configure gates leads to the settings.

One click creates the review session. If git sees no diff, the card says why and offers Choose a base ref…. The palette also offers Request review.

For any branch

Use this for work no session of yours covers, such as a branch you pulled from someone else.

1. Press Review a branch (b) on the Reviews page, or choose Review a branch… in the palette.
2. Check what git found: the branch, the number of changed files and the head commit.
3. Choose the Review mode: Simple (1) or Fleet (2).
4. Change the Base ref if needed: a ref, or a commit count such as HEAD~5. Blank uses the project default. If the base does not resolve, the dialog suggests one.
5. Press Create review session.

A branch has one review. If its branch already has one, the new request becomes that review's next round. To start over, archive the old review first.

For a branch in another worktree

When the project has more than one worktree, the dialog opens with a Worktree field (w). It starts on the worktree at the root, which is the review you get today. Pick another one to review its branch in its own folder: the dialog measures it there, and the review's agent and every Fleet gate work there. Your root and the other worktrees are not touched.

A worktree where a session is being built is greyed out with the session's ref: wait until its agent is done. A review that works in a parked worktree shows its name on its row, like a session does. From a terminal, invariant review --worktree <name> does the same.

Requesting a review needs the project's files, so it is not offered on the web.

Hand the review to an agent

1. Open the review and press Copy reviewer line (r).
2. Paste it into a new agent conversation. The reviewer must not have seen the plan.

The agent writes its findings through the invariant command, which validates each report. When it is done, the stage moves to Triage.

Fleet reviews

A Fleet review runs several gates: reviewers with their own focus, such as security or tests, each in its own context so they do not influence each other. You configure the gates in Settings, under Reviews: start from a preset or add your own. Each gate is Required or Advisory and ends with a verdict: pass, warning or block.

When you create a Fleet review, a launch pad opens:

• Paste one line into your agent: the orchestrator line. The agent hands each gate to a separate subagent and waits until every gate has reported.
• Run gates separately: one line per gate, for separate conversations, and Copy all.

While gates run, the review page shows which have reported and which are pending. A person can Waive… a pending gate with a reason; the board shows it waived.

Once every gate has reported or been waived, the board is sealed: the verdicts are recorded and can no longer change. Triage opens only then, so the number of findings is final. The board shows the overall result, one card per gate with its verdict and findings, and the next steps. Your triage decisions show beside the verdicts, never instead of them.

From the review's actions menu (m), Copy board markdown copies the board and Verify seal checks it was not changed. With GitLab connected, Post board (p) posts it to the merge request as an image, markdown or both.

Triage the findings

Each finding has a severity, a category, a place in the code and often a suggestion. Decide on each one:

• Stage it (s) to keep it.
• Discard it (d).
• Edit it (e) to change its wording, severity or category, then stage it.

Move between findings with J / K. ⇧S stages every finding the current filter shows, and u undoes a decision. Filter by decision (All, Open, Staged, Discarded), by severity or by agent. Peek shows the code in place; Open in editor opens the file.

The footer says what is left, such as "3 still need a decision". Every finding must be staged or discarded before you go on.

Plan the changes

Once every finding is decided, the review's main button (a) turns the kept findings into work.

1. Press Plan changes →. The staged findings become the review session's plan, on its Fix plan tab. The stage reads Fixes planned.
2. Press Copy fix line (f) and paste it into your agent. The stage reads Fixing, then Fixed when the fixes land.

A fix plan needs no separate approval: the findings you staged are the plan.

If you discarded every finding, the button reads Close review and the review ends as Closed. A review tied to no session has nothing to plan into: link it to a session first, or publish it.

Publish to GitLab

With GitLab connected in the project's Settings, the main button has a caret (⇧A) to choose Publish to GitLab instead of Plan changes. Choosing it switches the button and does not publish anything yet.

1. Press Publish to GitLab….
2. Check the merge request, the diff and the account the comments are sent as.
3. Choose whether to Include the review board, or to publish as general notes without source positions.
4. Press Create 4 draft comment(s).

The findings are created as pending draft comments. Nobody is notified until you press Submit review in GitLab. The review then ends as Published.

Re-review

A re-review checks that the fixes hold. It is the review's next round: a fresh reviewer reads the branch again at its new head, re-checks every finding the last round kept, and reads the files changed since first.

1. When the newest round is done, press Re-review (v) on the review, on the finished review session, or in the palette.
2. Check the dialog: the branch, the head of the last round against the head now, and the files changed since.
3. Choose the reviewers: As round 1 (the same mode), Simple or Fleet.
4. Press Start round 2. The new round's reviewer line is copied; a Fleet round opens the launch pad.

The dialog warns when nothing moved since the last round: the fixes may still be uncommitted. It refuses while the newest round is unfinished, or while another branch is checked out. A review that works in a parked worktree is measured in that worktree, which the dialog names.

A finding the next round finds unresolved comes back as a new open finding, marked as re-opening the old one.

Rounds on the review page

Under the review's header, one chip per round shows how it ended, such as "Round 2 · Fixed · 22 of 24 resolved". Under it, the selected round's four steps (Reviewing, Triage, Fixes, Done) with the one action of the current step. Move between rounds with , and ., and back to the latest with ⇧B.

An earlier round is a read-only record. Its findings show what the next round found: resolved, or unresolved and re-opened. Only the newest round can be triaged.

Comments

In an organisation project, members discuss a review, a finding or a passage. Press x to comment on the focused finding or the selected text, and ⇧L to show or hide the comments panel. Every round keeps its conversations. On This machine, the panel shows what comments are and leads to the Pro page.

Reviews on the web

An organisation's reviews are also on the web workspace. There you can read them, triage and plan the changes. Your decisions go through a teammate's machine: after Plan changes, the page says the change was sent, and a member's machine plans the changes and opens the fix session. Requesting a review or a re-review needs the branch's files, so it happens on a machine.

Archive a review

Press Archive review in the review's actions menu, or tick reviews on the list and press Archive. Nothing is deleted: the review moves to .invariant/reviews/.archive/, and every file stays readable on disk.

Switch the list to Archived to see archived reviews. From there you can delete a review for good; the app asks first. Its archived review sessions go with it.

Shortcuts

From the terminal

invariant review --session INV-015     # review the work of a session
invariant review --standalone --fleet  # review the current branch on its own, with the gates
invariant review --worktree feat-x     # review the branch of another worktree, in its folder
invariant review again INV-021         # start the next round
invariant review list                  # every review in this project

The reviewing agent runs the other invariant review commands itself. See Commands your agent runs.