Comments and mentions

By the end of this page you will have asked a question on a requirement and had it answered under it, told a teammate by naming them, kept a note from the client, closed the thread when the question was settled, and chosen which artefacts you hear about; you will also know what a client guest sees of the conversation and what each comment announces.

A comment is a note on one artefact: a question on a requirement, a finding on a story, a decision taken in the margin of a RAID item. Comments live in the Discussion panel at the foot of the artefact's flyout, under its links, on every page that has one: epics, work items, requirements, business rules, use cases, RAID items, decisions, data entities and glossary terms. A comment answers at most one earlier comment, so a thread is one level deep and reads as a conversation rather than a tree. A comment is either open to everyone who sees the artefact or internal, which a client guest never reads. Naming someone with @ tells them; following an artefact tells you of every comment on it. The first comment of a thread can be resolved when the question is settled, and reopened when it comes back.

Before you beginCopy Anchor Link

Read the discussionCopy Anchor Link

1. Open the artefact's page and open the artefact: its flyout opens from the row's menu, from View, or from a ?show= link someone sent you.
2. Scroll to Discussion, under the artefact's links.

Threads are listed oldest first, each with its replies indented under it. Every comment shows who wrote it and when (the full date on hover), an Internal badge when the client never sees it, a Resolved by badge on a settled thread, and (edited) when the words were rewritten. The panel's heading counts the people following the artefact.

Post a commentCopy Anchor Link

1. Write in Add a Comment at the foot of the panel. Bold, italics, lists and links are there; paste a key such as CRM-FR-12 to name another artefact.
2. Turn Internal on when the client must not read it. The switch is there only for roles that may post internally.
3. Press Post.

The comment appears at the end of the list, a toast confirms it, you become a follower of the artefact if you were not one, the people you named and the other followers are told, and comment.created goes out.

Mention someoneCopy Anchor Link

Type @ followed by the person's full name, @Jane Doe, anywhere in the comment. A first name alone, @Jane, works when exactly one Jane may read the comment; a shared first name names nobody rather than someone at random. Case, bold and links around the name change nothing. The people named receive a mention alert, routed under the Mentions class of their notification settings, wherever the comment is; a client guest is told only of open comments, never of internal ones, even when named.

Reply in a threadCopy Anchor Link

1. Press Reply under the first comment of a thread. A chip above the editor says whom you are answering; Start a new thread instead drops it.
2. Write and press Post.

A reply takes the audience of its thread: under an internal comment it is internal whatever the switch says, and the switch is disabled while you reply. Replies cannot be replied to, so a long discussion stays one conversation under one question.

Resolve a threadCopy Anchor Link

Press Resolve under the first comment when the question is settled. The thread is marked resolved with your name, its text dims, and comment.resolved goes out. Reopen brings it back, with comment.reopened. Only the first comment of a thread is resolved; its replies follow it. The author of the thread and anyone with comment:update may resolve and reopen.

Edit or delete a commentCopy Anchor Link

• Edit opens your own comment in the editor; Save rewrites it and marks it (edited), anyone newly named is told, and comment.updated goes out. Cancel keeps the old words.
• Delete asks once, inline, and then removes the comment; the replies under a first comment go with it, and one comment.deleted goes out for the comment you named. Keep backs out.

You edit and delete your own comments; comment:update and comment:delete let a moderator do the same for anyone's.

Follow an artefactCopy Anchor Link

Press Follow in the panel's heading to hear of every comment posted on the artefact; the button reads Following once you do, and pressing it again stops. Commenting follows the artefact for you without asking. A follower's alert is routed under the Planning class of their notification settings for the planning artefacts; a client guest who follows hears of open comments only. Followers are told of comments, not of edits, resolutions or deletions, which the artefact's own events carry.

All the fieldsCopy Anchor Link

Who hears whatCopy Anchor Link

A client guest is a follower like anyone else, but hears of open comments only.

What happens nextCopy Anchor Link

• comment.created, comment.updated, comment.resolved, comment.reopened and comment.deleted go out with the artefact, the author, the audience and the thread, never the words; see the comment.* events. An internal comment is announced like any other, because webhook endpoints are the team's.
• A comment is not a version of the artefact: posting, editing and resolving change nothing on the record itself. The activity log keeps each comment's own changes, so an edit is never silent.
• Heimdall and an agent connected over MCP read the discussion before they draft or act, so a question answered in the margin reaches them without being pasted into the artefact.

ManagingCopy Anchor Link

• A moderator with comment:update edits and resolves anyone's comment; with comment:delete deletes anyone's. Both are given to project managers by default.
• Guests may comment is a project setting, on by default; off, a client guest reads the open comments and posts nothing. Internal comments stay internal whatever the switch says.
• An artefact deleted takes its comments with it.
• A deleted account leaves its comments in place, with the author shown as someone.

Heimdall on this pageCopy Anchor Link

Heimdall reads the discussion of an artefact when it drafts for it or answers about it, and an agent connected over MCP posts its own comments with comment_on_item when it has a question, a finding or a decision to record: before it moves a status, after it links a pull request, when a criterion cannot be verified. Neither edits, resolves or deletes what anyone said, and neither follows anything: the conversation stays with the people in it.

From the API and MCPCopy Anchor Link

PermissionsCopy Anchor Link

Frequently askedCopy Anchor Link

RelatedCopy Anchor Link

• Notifications — where the Mentions and Planning alerts go
• Traceability — the links panel above the discussion
• Project settings — whether guests may comment
• Revisions and versions — what a comment is not
• comment.* webhook events