---
title: "Comments"
description: "Discuss a passage of a spec file with your team and the AI, right next to the text it is about."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.myspec.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Comments

Comments let you discuss a specific passage of a spec file. Each comment starts
a **thread** that is attached to the text you selected, and the thread follows
that text when the file changes.

## Add a comment

1. **Select a passage**

   Open a spec file from the file explorer, or open it in the spec editor. Then
   select the text you want to talk about.
2. **Select Comment**

   A **Comment** button appears next to your selection. Select it. The comments
   panel opens with a box for your comment.
3. **Write and post**

   Type your comment and select **Comment**.

You can comment on the latest revision of a live file, in these views:

- the file viewer's **Preview** and **Raw** views
- the spec editor's **Rich Text** and **Source Mode** views

The **Comment** button does not appear in a diff (**Diff** or **Diff Mode**), on an
older revision, or on a file in the **Trash Bin**.

Passages that have open threads are highlighted in the file. Select a
highlighted passage to open the comments panel at its thread.

> **Commenting needs Write access**
>
> Writing, replying to, resolving and reopening comments, and editing or
> deleting your own, need **Write** access on the project. With **Read**
> access you can read every thread and jump to its passage, but the
> **Comment** button doesn't appear and the threads have no controls. See
> [Teams and project access](/guides/teams-and-project-access/).

## Reply, resolve and reopen

Each thread shows the passage it is about and every comment in it.

- **Reply**: add to the discussion.
- **Resolve**: mark the point as settled. Anyone with **Write** access to the
  project can resolve a thread. Resolved threads move out of the way.
- **Reopen**: bring a resolved thread back if the point turns out not to be
  settled.

## Edit or delete your own comments

You can edit or delete only the comments you wrote.

- Select **Edit**, change the text, then select **Save**.
- Select **Delete**, then confirm with **Delete for everyone**.

If you delete the first comment of a thread that has replies, the thread keeps a
**Comment deleted** placeholder, so the replies still make sense. A deleted reply
simply disappears. Deleting the first comment of a thread with no replies removes
the whole thread.

## Comments follow the text

When someone saves a new version of the file, each thread finds its passage again
and moves with it. Rewording the sentences around a commented passage does not
break the link.

### Detached comments

If the passage a thread was about is gone, the thread is not left pointing at the
wrong place. It moves to the **Detached comments** section of the file's group in
the comments panel: "The text these referred to has changed. Select a new passage
to re-attach one."

To re-attach a thread:

1. Open the file, on its latest revision.
2. Select the passage the thread should now point to.
3. In the detached thread, select **Attach to selected text**.

## The comments panel

All comments live in one floating panel. Open it with the comments button (a
speech bubble) in the top bar of a project, on every tab, or in the header of a
session. The button's badge shows how many threads are unresolved across the
whole project.

- **Grouped by file.** The panel lists the project's unresolved threads, grouped
  by spec file. Use a group's file button to open that file.
- **The open file comes first.** When you have a file open, its group moves to the
  top and shows all of its threads: unresolved ones in document order, then
  detached ones, then resolved ones behind a count such as "2 resolved".
- **Jump to the text.** In the open file's group, select a thread's quoted
  passage to scroll the file to it.
- **It stays where you put it.** Drag the panel by its header. It keeps its place,
  and stays open, as you move between the project page and your sessions.
  Reloading the page closes it and puts it back in the corner.
- **It never opens by itself**, not when a comment arrives and not when you open a
  file. It opens when you select the header button, the **Comment** button or a
  highlighted passage, or follow a notification about a comment.
- **On a narrow screen** it appears as a sheet at the bottom of the screen
  instead.

The file explorer also shows a count of open comment threads next to each file,
so you can find the discussion without opening every file.

## The Discussions tab

A project's **Discussions** tab shows the comments panel full screen: every
comment thread in the project, grouped by spec file. The tab's badge shows how
many threads are open.

- **Open**, **Resolved** and **All** pick which threads to show. **Open** is
  selected when you arrive and shows the number of open threads.
- The spec file picker, set to **All spec files** at first, shows the threads
  of one spec file.
- The search box finds threads by comment text, quoted passage, file path or
  a person's name.
- **Reset filters** goes back to the open threads of every file.

Each thread has the same actions as in the comments panel: **Reply**,
**Resolve** or **Reopen**, and **Edit** or **Delete** on your own comments.
Select **Open in file**, or the thread's quoted passage, to open the spec file
in the preview with the comments panel showing that thread.

To start a new discussion, open a spec file, select some text and choose
**Comment**. See [Add a comment](#add-a-comment).

With **Read** access you can read every thread and use **Open in file**, but
you can't reply, resolve or reopen.

## Mention someone

To mention a person in your organization, type `@` followed by their username,
for example `@jane`. You can find your own username on your **Profile** page.

The person you mention gets a notification, if they can open the project.
Mentions inside code, in backticks or a code block, are ignored.

You also get a notification when someone replies to a thread you started or
replied to. See [Notifications](/guides/notifications/) to choose which of these
also reach you by email.

## Comments from the AI

During a Generate or Edit session, the AI can read a file's comment threads, open
a new thread on a passage, and reply to yours. Coding agents connected through the
[MySpec MCP servers](/mcp/tools/) can read threads, open them and reply too, and
edit or delete their own comments.

These comments are labelled **MySpec AI**.

> **People close reviews, not the AI**
>
> The AI and connected agents cannot resolve or reopen a thread, and cannot
> re-attach a detached one. Deciding that a point is settled stays with people.

## Comments on files in the Trash Bin

When a file is in the **Trash Bin**, its discussion stays readable. You can still
resolve and reopen threads and edit or delete your own comments, so open review
items can be closed out. You cannot add new comments or replies, or re-attach a
detached thread.

In the comments panel, a trashed file's group is marked **Trashed**.

## Share links

[Share links](/guides/share-links/) show the shared spec files only. Comments are
never included, and people viewing a share link cannot comment.

## Troubleshooting

| Message | What to do |
|---|---|
| That passage could not be found. Select it again. | The text changed after you selected it. Select the passage again. |
| Select a shorter passage. | Your selection is too long for a comment. Select less text. |
| That is too long to save. Shorten it and try again. | Shorten your comment. |
| This comment was edited elsewhere. Reload it and try again. | Someone changed the comment after you opened it. Select **Reload**, then make your edit again. |
| The file was busy. Nothing was saved — try again. | Select **Try again**. |
| That comment is no longer there. | Someone deleted it. |
| This no longer applies — the file or thread has moved on. | The file or thread changed, for example it was moved to the **Trash Bin**. Check its current state. |
| You have read-only access to this project, so you can't change comments. | Your role on the project is **Read**. Ask a project admin for **Write** access. |

Source: https://docs.myspec.dev/guides/comments/index.mdx