# Review mode on specifications

To comment on a running application in a coding session, see
[Review mode on the live preview](/user-guide/sessions/live-preview-review).

Review mode is how you review a feature's or a component's specification together with an AI agent.
You comment on the passages that are wrong or unclear, then send the comments to the agent. It reads
each comment and the code it concerns, revises only the passages your comments point at, answers
under every comment, and proposes the result for your review. Nothing in the specification changes
until you apply the revision.

<Availability permission="Comments: Create to comment. Features: Update to send the comments to the agent, plus Can edit on a private feature." />

## Key concepts

**Open comment.** A comment on a passage of the document that nobody has resolved yet. When you
send, the agent gets every open comment with the replies under it. Replies on their own, resolved
comments, general comments, and comments that ask PM aren't sent: PM answers those itself. See
[Ask PM in comments](/user-guide/product/ask-pm-in-comments).

**General comment.** A comment on the whole document rather than on a passage. General comments
sit at the top of the comments beside the document. The bar doesn't count them.

**Revision.** The specification as the agent proposes to change it. It waits for your review, like
a draft from a refresh, and applies only when someone who can change the feature chooses to.

## The review bar

While Review mode is on, a bar above the document says where the review stands:

| The bar shows | What it means |
| --- | --- |
| **N open comments** and **Send to agent** | You can send the open comments, for example **3 open comments**. With none open yet, the bar says **Select a passage to comment on it.** |
| **The agent is revising from N comments** and **Stop** | The agent is working on the comments you sent. |
| **The agent's revision is ready** and **Review changes** | The revision is waiting for your review. |
| Another revision of this document is in progress, or waiting for review | Another draft of the specification, from a refresh, a composition or a code chat, comes first. Send your comments once it has been applied or dismissed. |

If you can comment on the feature but can't change it, the bar shows the open comments and
**An editor can send these comments to the agent.**

## Reviewing with the agent

### To turn on Review mode

1. Open the feature or the component.
2. Choose **Review** in its header. It shows how many comments are open.

The document becomes read-only, and the review bar appears above it. Review mode stays on when you
reload the page, and a link you copy while it's on opens the document in Review mode. To turn it
off, choose **Review** again.

### To comment on a passage

1. Select the text you want to comment on. The comment box opens straight away.
2. Enter your comment. Type @ to mention someone.
3. Choose **Comment**.

The text stays highlighted, the comment appears beside it, and the bar counts it. Repeat for each
passage you want the agent to look at.

### To leave a general comment

A general comment is about the whole specification rather than one passage of it. You can leave one
whether or not Review mode is on, and it isn't sent to the agent.

1. Choose **Add a general comment**, at the top of the comments beside the document. In a narrow
   window, it's the comment icon above the avatars beside the text.
2. Enter your comment. Type @ to mention someone.
3. Choose **Comment**.

The comment appears at the top of the comments, under **Add a general comment**. General comments
stay there, newest first, above the comments on passages. Comments that an AI agent or a teammate
adds without selecting text appear there too. Everyone you mention is notified.

### To send the comments to the agent

1. Choose **Send to agent**.

Productmind saves the document first, so the agent reads what you see. The bar then reads
**The agent is revising from N comments**, for example **The agent is revising from 3 comments**,
and the feature's row in the **Features** list shows that it's being revised from comments. The
agent works in the background, so you can leave the page and come back.

If the run can't start right now, **Send to agent** is grayed out and the bar says why, with the
action that fixes it: **Top up** when your organization's balance can't pay for it, or
**Connect your Productmind agent** when your workspace has turned off Productmind cloud sessions
and none of your Productmind agents is online.

### To review the agent's revision

1. When the bar reads **The agent's revision is ready**, choose **Review changes**.
   The comparison opens, with the agent's summary and any
   [audit findings](/user-guide/product/audit-findings) above it, and shows each change against the
   current document. Its header says **Revision from N review comments**.
2. Choose **Reject** on any change you don't want, or **Edit** to rewrite the revision.
3. Choose **Apply N changes**, for example **Apply 2 changes**, or **Dismiss** to throw the revision
   away.

Applying the revision resolves the comments you sent, even those whose changes you rejected.
Dismissing it leaves them open, so you can refine them and send them again. To decide later, choose
**Close review**: **Review changes** reopens it.

Under each comment you sent, the agent's reply says what it changed, or why it kept the text, with
the file and line in the code that shows it. Its replies are marked as the agent's.

### To stop the agent

1. Choose **Stop** on the review bar.

The agent stops, and proposes nothing. Your comments stay open. Only the person who sent the
comments, or someone who manages the workspace, can stop it: for anyone else, the bar says who can.

## How Review mode behaves

**The code decides.** The agent checks every comment against the code. Where the code agrees with a
comment, it changes the passage. Where the code contradicts it, it keeps the text and says why in
its reply, pointing at the code. Where the code can't settle it, such as a product decision, it
keeps the text and says so.

**Only what your comments point at changes.** Everything else in the specification comes back
exactly as it was, so the comparison shows the changes your comments asked for, and anything those
changes made inconsistent elsewhere. One exception: when a link to the code elsewhere in the
document no longer points at the right place, the agent repairs it and lists it in its summary.

**On a feature made of components, fix the component.** A feature's specification is written from
its components' specifications, and composing it again rewrites it, so a fix made only in the
feature's own text can be lost. When a mistake comes from a component, the agent names that
component in its reply and in its summary: review that component's specification too.

**The agent works read-only.** It reads the code of the feature's linked applications, and of the
components the feature is made of. It never changes your code, starts a preview or opens a pull
request. A component with teams of its own, which narrow who can see it, is left out.

**A feature holds one draft at a time.** While the revision waits for review, nothing else can
propose a draft for that feature: a refresh, a composition or a code chat. While the agent revises a
component, the feature above it can't be composed.

**A revision isn't a scan.** The **Deep scan** filter on the Features list doesn't count it.

**What it costs.** Each **Send to agent** runs one AI agent, like a refresh. In Productmind's cloud
it uses AI credits. When your [Productmind agent](/user-guide/tools/productmind-cli) runs it on
your own machine, it uses none of your AI credits, and it's one user-hosted session instead. See
[Usage](/user-guide/settings/billing-and-payments/usage).

## Permissions

| To | You need |
| --- | --- |
| Turn on Review mode | To be able to change the feature: **Features: Update**, or a team with **Can edit** on a private feature |
| Comment, and reply | **Comments: Create** |
| Send the comments to the agent | **Features: Update**, plus **Can edit** on a private feature |
| Review and apply the revision | To be able to change the feature, as for any draft |
| Stop the agent | **Features: Update**. To stop a revision someone else started, also to manage the workspace |

The people who manage the workspace are an **Owner** or **Admin** of your organization, the
workspace's owner, and its admins. See
[Private features](/user-guide/product/private-features#permissions) for what a private feature's
teams change.

## Limits

One send carries up to 50 open comments, the oldest first. When more are open, the bar says so, for
example **Only the oldest 50 of 62 are sent. Send again for the rest.**

## Troubleshooting

### Review is missing

The entry is a domain, which has no specification of its own to review, or you can't change the
feature. If you can't change it, its document is read-only already: select text to comment, and ask
someone who can edit the feature to send the comments.

### Send to agent is missing

You can't change the feature: your role doesn't include **Features: Update**, or the feature is
private and your team has **Can view**. The bar reads
**An editor can send these comments to the agent.** Ask someone who can edit the feature to send
them.

### Send to agent is grayed out

No comment is open on a passage yet, or the run can't start right now: point at the button, and
read the bar, to see why. See [To send the comments to the agent](#to-send-the-comments-to-the-agent).

### "There are no open comments on this document to send"

Every comment on the document is resolved, a reply, or a general comment, which isn't attached to
a passage. Select a passage, comment on it, and send again.

### "Link at least one application with a repository before sending comments to the agent"

Neither the feature nor the components it's made of has a linked application with a repository.
Link one in the **Applications** panel. See
[To link an application](/user-guide/product/features#to-link-an-application).

### "A description proposal is already in progress for this feature"

Another draft of the specification is being written or waits for review. Apply or dismiss it, then
send again.

### A comment is still open after I applied the revision

It wasn't sent: you added it after you sent the others, or more than 50 comments were open. Send
the open comments again.

### The comparison shows a change no comment asked for

The agent changed a passage that your comments made inconsistent, or repaired a link to the code
that no longer pointed at the right place. Its summary lists each repair. Choose **Reject** on any
change you don't want.

## Related topics

- [Features](/user-guide/product/features)
- [Code conversations](/user-guide/sessions/starting-a-session#code-conversations)
- [Audit findings](/user-guide/product/audit-findings)
- [Private features](/user-guide/product/private-features)
- [Templates](/user-guide/engineering/agents/templates)
