Reviews
Reviews provide a formal review process for one or more documents. They support participant roles, per-item opinions, comments, checklists, and an optional AI review pass. Reviewing happens inside the document editor; the Reviews pages give you the overview and management surface.
Creating a Review
You can start a review two ways:
- From the Reviews list — click New Review. A dialog opens with a document picker; tick one or more documents to review together, give it a title and an optional description, and add participants.
- From a document — open the document, and on the ribbon’s Review tab click Start review (or New if the document already has reviews). The review is scoped to that document.
In both cases you are added as the review Lead automatically, and you can add other participants as Reviewer or Observer. Click Create Review to finish.
A review starts in Preparing and captures each in-scope document’s current commit as its starting point, so the protocol can later show exactly what changed during the review.
Multi-document scope
A single review can span several documents. The document picker in New Review accepts multiple selections; the review’s summary, changes report, and protocol then aggregate across every document in scope, and the protocol groups its item details per document.
Reviewing in the Document
Open an in-progress review by clicking a document in the review’s Documents list on the detail page (or from the editor’s Review tab). This opens the document in review mode.
- The review side panel opens on the right (see below).
- A gutter overlay floats a small control cluster beside each work item in the right margin:
- the team aggregate — other reviewers’ ✓/! tally (display-only)
- your own OK / Issue segmented control
- a Comment pill that opens the item’s thread (it shows the unresolved, then total, comment count)
- Set your opinion from the gutter, or from the ribbon’s My opinion group (OK / Has issues) once an item is selected.
- Add comments with New comment in the ribbon, or via the Comment pill.
- Opinions and comments are batched and saved together with the document Save.
- Click Exit on the ribbon (or the ✕ in the panel header) to leave review mode.
The review side panel
The panel header shows the review’s status badge, its title (linking to the review page), a participants popover, and an exit button. Below it a progress strip summarises reviewed / total · issues · comments (with an AI count when AI findings are open).
A three-way switch scopes the panel:
| Tab | Scope | Shows |
|---|---|---|
| Findings | Whole document | The triage list of flagged items + entry/exit checklists |
| Details | Selected item | The item’s detail panel |
| Review | Selected item | The item’s comment thread, AI-finding triage, per-item checklists |
Details and Review are enabled only once a work item is selected.
The Findings list has one row per flagged item — an item with an unresolved AI finding, an unresolved comment, or any “has issues” opinion. Filter chips narrow it to All, Open issues, AI, or No opinion, and Dismiss all info clears the low-severity AI findings in one click. Clicking a row selects that item and opens its Review thread.
Participants
| Role | Purpose |
|---|---|
| Lead | Runs the review; the creator becomes Lead automatically |
| Reviewer | Provides opinions and comments on items |
| Observer | Follows the review without being expected to opine |
Participants are edited inline on the review detail page: click Edit in the Participants panel, change roles (via the role dropdown), remove people, or Add participant, then click Save — the whole set is committed at once. A review must always keep at least one Lead. Editing is available while the review is open (not once it is Closed or Cancelled), and additionally requires review permissions in the workarea — see Roles & Permissions.
Review Lifecycle
| Status | Description |
|---|---|
| Preparing | Scope and participants are being configured |
| In Progress | Reviewers examine items and provide opinions |
| Closed | Review is complete, protocol generated |
| Cancelled | Review was ended before completion |
Status changes go through the status dropdown in the review detail page header — reviews follow a configurable workflow, so the available transitions depend on the current status. Closing a review records the closing commit and generates the protocol.
Opinions
- OK — The item meets requirements
- Has Issues — The item needs changes
Summary cards on the review detail page count items by outcome; an item with both OK and Has-Issues opinions counts as having issues.
Comments
Reviewers can add markdown comments to individual items or to the document as a whole. Comments can be marked as resolved (shown with a checkmark); the review detail page displays the total and unresolved counts.
AI review
While a review is In Progress, participants can run an optional AI review pass over the in-scope documents. It flags requirement-quality issues (atomicity, ambiguity, testability, passive voice) as AI-authored comments you triage. See AI review.
Checklists
Reviews can include checklists allocated as:
- Entry criteria — Expected to be complete before the review starts
- Exit criteria — Expected to be complete before the review closes
- Per-item checklists — Applied to specific items in the review
Each checklist tracks completion with a progress bar. Incomplete entry/exit criteria produce warnings when starting or closing — they do not block.
Review Detail Page
The detail page shows:
- Header — Title, the status dropdown, and Generate report / View Protocol actions
- Summary cards — OK, Has Issues, Comments, and Opinions counts
- Description — Markdown-formatted review description
- Changes since review start — a per-document diff (added / modified / deleted), each row opening that document in compare view
- Checklists — Entry/exit criteria with completion tracking
- Review Period — the start and close commits that pin the review’s scope
- Comments — List with author, date, and resolved status
- Sidebar — the editable Participants panel, the in-scope Documents (each showing its resolved status badge and opening in review mode), and a Timeline
Review Protocol
After closing a review, a protocol is generated summarizing per-item opinions and comments, checklist completion, and what changed during the review period. See Review Protocol.