Skip to content

Review Comments

Audience: authors and reviewers.

Review comments let reviewers and authors discuss a specific passage of a document on the document, during its review round — instead of in email or a separate tool. Comments are records: they are anchored to the text, unchangeable once written (with one narrow deletion window, §1), and resolvable, and they can gate the release.

1. Adding an anchored comment

Select a passage in the document (either while reading it or while editing the draft) and choose Add comment. Your comment is anchored to that block and the quoted text, so it stays attached to the right place even as the surrounding text is edited. Type your note and post it.

  • Anyone holding a workflow role on the document (Author, Reviewer, or Releaser) may comment — and so may anyone who holds edit-draft rights in the project, whether or not they hold a workflow role. Whoever may rewrite a working draft may also annotate it; the alternative was pushing exactly the conversations a QMS exists to keep into email. The Add comment affordance only appears when you are allowed to.
  • Replies are one level deep — a comment and its direct replies form one thread.
  • Comments are plain text and cannot be edited. They can be deleted in one narrow form: your own comment, while the version is still a draft, and only while nobody has replied to it (a reply is another participant's record, and it stays). The text disappears; the fact that you deleted it stays in the audit trail. Once the version goes into review, or once a reply lands, the comment is part of the review record — to correct yourself, add a reply.
  • The document's Author-role holders are notified when a comment is added.

2. Resolving comments

When a comment has been dealt with, Resolve it. Resolving is the signal that the point is closed; a resolved thread collapses out of the way (available behind a disclosure) and leaves no inline marker on the text — resolving visibly cleans the passage. A resolved comment can be re-opened (Unresolve) if the discussion needs to continue.

3. The release gate

For most document types, a document cannot be released while any review comment is unresolved. This is the comment quality gate (configurable per type in Scope configuration). When you try to release, the action tells you how many comments are still open (e.g. "3 unresolved review comments"); releasing becomes available the moment the last open comment is resolved.

Under automatic release mode the effect is the same: the final approval does not release the document while comments are open — it waits, and a releaser finishes the release once they are resolved. Resolving a comment never releases a document by itself.

4. Who can see comments, and when

  • While the document is Draft or In review, the comments follow the document: anyone who may read the version reads its comments. The discussion belongs to the working draft, and hiding it from people who can already read the text it annotates would protect nothing.
  • After release, review comments are not shown to ordinary readers at all — a released document is the clean, controlled artifact. Its existence is not even hinted at. Workflow-role holders and quality managers (CONFIGURE_REVIEW_POLICY) can still reveal the round's comments: in the right-hand rail they get a collapsed Review comments card, carrying its count like References or Trace links do, and opening it mounts the list and the in-text markers. So the review history stays auditable without cluttering the released document.

Updated 2026-09-24 (register row 108 item 5): after release the reveal is the rail card's own header — a chevron, the title and the count badge, exactly like References and Trace links — rather than the stroked bar it used to be. Same act, same permission, one grammar.