| name | annotate |
| description | Work through markdown annotations (comments and questions queued on documents linked to this thread). Use when the user asks you to address annotations, comments, review feedback, or questions on a markdown document. |
Working through MD Annotate annotations
Documents annotated with MD Annotate carry inline comments and questions on
selected text. When linked to this thread, they queue here for you to answer
one at a time.
The flow
annotations_status — list pending annotations (id, quote, kind, age).annotations_next — take the next one. It marks it in-progress and prints
the file, the selected text with <selected> tags around the surrounding
lines, and the comment thread. It refuses to advance while another
annotation is in progress — reply, resolve, or annotations_end it first.annotations_reply — put your full answer here
(annotationId, text, and resolve: true when fully addressed). The
user reads your reply in the annotation UI, not in this chat — do not
repeat it as chat prose.annotations_resolve — close an annotation after replying.
Rules
- Questions are answer-only. Never edit the document for a question —
answer in the
annotations_reply call.
- Comments may warrant an edit. For a comment you may edit the document
to address it, and say what you changed in the reply.
- Don't answer stale context. If
annotations_reply is blocked because
the user added a new comment since you last read the annotation, re-read
with annotations_show and address the latest comments before retrying.
- One at a time. Take the next annotation only after the current one is
replied or resolved.
annotations_show <id> reprints an annotation at any
time without changing its state.
CLI (for scripts and shells)
The same operations exist as bb annotate (from a thread context, or with
--thread <threadId>): next, status, show <id>, reply <id> "text" [--resolve], resolve <id>, start <id>, end <id>.
