Skip to content

Comment assistant

Outcome

When a client comments on a specification you shared by link, Threadory drafts a reply and, when the remark calls for it, a change to the document. You review the draft in Approvals. Nothing reaches the client and nothing changes in the document until a team member approves it.

Before you begin

  • The document is a native document with an active public link, and the client commented through that link.
  • You are a project member or above: switching the assistant on and approving its drafts both need that role.

The assistant is off by default and is switched on per document, not per project.

Steps

  1. Switch the assistant on for the document — from an MCP client, ask to run kb_set_document_assistant with the document's doc_line and enabled: true (or call PATCH /projects/{project_id}/documents/{doc_line}/assistant with {"enabled": true}).

  2. Wait for a client comment. For each new comment or reply from the client, the assistant drafts one proposal. It does not answer:

  3. a resolved thread;

  4. a short reply such as "thanks" right after your team's answer;
  5. comments written by project members.

It drafts against the version the client commented on. The proposal is a reply only, with the reason in its rationale, when:

  • the document is too complex to change safely — it uses Markdown outside the simple subset the assistant edits (footnotes, raw HTML, headings with formatting, nested quotes and similar). This is the most common reason;
  • the client commented on an older version than the current one;
  • a newer draft is in progress;
  • the comment is not tied to a section of that version.

Edits are only ever proposed inside the section the comment is about. Team-only (internal) notes are never shown to the assistant.

  1. Open Approvals and select the proposal "Reply to a reader on …". It is marked customer-facing: approving it sends a message to someone outside the team, so the page asks you to confirm. Telegram notifications for it carry only a link to the web app, never Approve or Reject buttons.

  2. Read the summary: the proposed reply first, then the proposed edits (each as find → replace), then the client's comment, shown between BEGIN UNTRUSTED COMMENT TEXT and END UNTRUSTED COMMENT TEXT lines. The full fields are reply_text, patch, rationale and confidence.

  3. Choose an action:

  4. Approve — the reply is posted in the thread under your name and the client gets it by e-mail; the edits, if any, are written as a new draft version that resolves the thread;

  5. Edit payload, then Edit & approve — change reply_text, the patch list (set it to null to send only the reply) or publish_status (draft or in_review) before sending;

  6. Reject — nothing is sent and nothing changes.

  7. If the edit can no longer be applied when you approve — the document changed meanwhile, the text to change is gone, or the document store is briefly unavailable — nothing is sent yet. Instead a second proposal appears in Approvals: "Reply only (the change could not be applied): …". Its summary says why the change failed and shows the approved reply. Approve it to send the reply alone; the document is not changed, and any edit you add to it is ignored. Reject it to send nothing.

Verify the result

The thread on the document page shows your reply, and the client sees it on the public page. If the proposal carried edits, the document has a new draft (or a version in review) with the change note "Addresses 1 comment (§…)", and the thread is marked resolved in that version. If a "Reply only …" proposal appeared instead, the reply is in the thread only after you approve that second proposal; the document stays as it was.

Common problems

Symptom Likely cause What to do
No proposal after a client comment The assistant is off for the document, the thread is resolved, the comment was a short acknowledgement, or the document store was briefly unavailable — then the run ends failed (visible in the runs list) and only a new client reply starts another run Check assistant_enabled on the document; reopen the thread if it needs an answer; after a failed run, answer the comment yourself
The approved reply was not sent The edit could not be applied (the document moved on, the text no longer matches, or the store was down), so a "Reply only (the change could not be applied): …" proposal is waiting Approve that proposal in Approvals to send the reply without the change
The assistant only ever proposes replies for a document The document uses Markdown outside the simple subset the assistant edits Make the edit yourself; the replies are still drafted
In a very long thread the draft overlooks something said early on The thread is shortened to fit what the assistant can read: the first comment, the one being answered and the most recent messages are kept, and the gap is marked Edit the reply before approving, or answer the thread yourself
A draft follows instructions written in the comment The client's text is treated as data and the assistant is told to ignore instructions in it, but no filter is perfect Reject the proposal; nothing is sent without your approval