Questions in Plans and Documents

An agent can put a question in a plan or a document when it needs you to make a decision. Plannotator shows each question as a card with choices. You answer in place, and the answers go back to the agent with the rest of your feedback.

Questions work in plan review, plannotator annotate on a markdown file or folder, and plannotator last. They do not work on HTML pages, live apps, diagram files, or in code review.

What the agent writes

A question is a :::question block. Blank lines between the parts are recommended, so the block also reads well on GitHub.

:::question
Where should losing conflict versions be kept?

Last-write-wins silently drops the loser unless we keep it somewhere.

- [ ] Nowhere — accept silent loss for v1
- [ ] Local only, purged after 30 days — cheap, no server change
- [ ] Server-side per user — survives reinstall, needs a retention policy

Recommended: Local only, purged after 30 days
:::

:::question asks for one choice. :::question-multi accepts any number of choices. :::question-text asks for free text.
The first line is the question. Other lines before the choices are context. Agents are told never to send a bare question: a sentence or three on what the choice affects, what they know, and why they recommend what they do.
Recommended: names the agent’s recommendation. It matches a choice by its label, or by the start of it (Recommended: Unpin it matches - Unpin it: the toast says so). If it matches no choice, or the start of more than one, Plannotator adds it to the list as one more answer, tagged Recommended, right before Other…. Picking it, or Accept recommended, answers with that text.
- [x] marks a choice as already settled. Agents use it when they resubmit a plan with a question you already answered.

Optional lines and picture choices

A question can carry a few more lines, each on its own line after the question. They are all optional, and most questions need none of them. The Plannotator Inbox draws them on the card as described below; in plan review and annotate they show as plain text under the question:

Stakes: <one sentence>: what the choice affects. The card shows it in bold under the question.
Shows: ![alt](path) or Shows: [name](file): the one picture or file the decision is about. The card shows it as a chip that opens it.
Why: <one line>: why the agent recommends its answer. The card shows it under the choices, as “Why : …”.
Reversible: no — <why>: the answer cannot be taken back. The card shows a Can’t be undone tag.

When the options are visual, a choice can be a picture: - [ ] Label — ![alt](path) consequence. The card draws the choices as picture tiles. Click a picture, or its label, to pick it; the zoom button in the corner opens the picture large without picking it. The answer the agent gets back is the label.

:::question
Which checkout drawer should ship?
Stakes: ships to all of checkout on Thursday; changing it later costs a week of QA.

- [ ] A · Total on top — ![Drawer A](drawer-a.png) closest to today
- [ ] B · Total pinned with Pay — ![Drawer B](drawer-b.png) the total never scrolls away

Recommended: B · Total pinned with Pay

Why: on a phone only B keeps the total next to the button.
:::

If a picture cannot be shown, the choices are ordinary rows with their labels. None of these lines changes which answer belongs to which question.

How you answer

Each card shows “Question N of M” and a status: Open, Answered, Skipped, or Settled.

Pick a choice, or type your own answer in Other…. “Other…” is always available.
Add note adds a comment to your answer.
Skip tells the agent you chose not to answer.
Accept recommended fills in the agent’s recommendation. It shows only while the question is open and has a recommendation.

You can still select and comment on the question text like any other text.

The header shows how many questions are answered, for example “2/4 answered”. Click it to go to the next open question. The annotations panel lists every question in a Questions section above your comments. Answers are saved in your draft, so they survive a reload, and Mod+Z undoes them like other annotations.

What the agent gets back

Answers come first in the feedback, under “Answers to your questions”:

## Answers to your questions

2 of 3 questions answered.

### Q1. Where should losing conflict versions be kept? (line 22)
Answer: Local only, purged after 30 days (your recommendation)
Note: keep the log reachable from the debug menu.

### Q2. Which sync indicators ship in v1? (line 45)
Answer:
- Per-document synced / pending / failed dot
- Global offline banner

### Unanswered
- Q3. Describe the manual test you'd run before calling offline sync shippable. (line 58)

“(your recommendation)” tells the agent you accepted its recommendation. Questions you did not answer are listed under “Unanswered”.

Plan review: Send answers

When your only feedback on a plan is answers, the main button reads Send answers. The agent then gets a message that says you answered its questions and asks it to put the answers into a revised plan and resubmit. It does not get the “your plan was not approved” message. When you also leave comments or edit the plan, the button reads Send feedback and the agent gets the normal feedback message with the answers at the top.

On resubmit, the agent either removes an answered question and writes the decision into the plan, or keeps it with the chosen choice marked - [x]. A settled choice shows as selected with a “Settled” tag, and you can still change it.

You can change the message the agent receives with the answered key in prompts.plan. See Custom Feedback Messages.

[!WARNING] In Claude Code, Approve does not send answers or notes to the agent. If you approve with answers, Plannotator warns you first. To send answers, use Send answers.

In the Plannotator Inbox: Stopped and Holds up

In the Plannotator Inbox, a question block can carry two more lines that sort the thread in your list. They are for the Inbox only; in a plan or document they are ordinary context text.

:::question
Which database password should I use for staging?

Stopped: can't run the migration without it
Holds up: staging deploy; release notes

- [ ] The one in 1Password "staging-db"
- [ ] Make a new one
:::

Stopped: <why>: the agent cannot go on until you answer. The thread goes first, under Stopped on you. Agents are told to write it only when they truly cannot continue.
Holds up: <work>; <work>: the agent goes on, and the named work waits on your answer. The thread shows under Holding up work, unless a question also says Stopped:, which wins.
A negative value (no, none, n/a, a dash) means no stop: Stopped: no is read as if the line were not there, and a Holds up: entry none holds nothing up.
A question that says Stopped: or Holds up: should also say Stakes:. When it does not, the agent is reminded when it sends the message; the message is sent either way.

Teaching your agent to ask

The plannotator skill has a section, “Asking the reviewer questions”, with the syntax and the rules for when to ask.
The optional Plannotator Flavored Markdown reminder ({ "pfmReminder": true } in ~/.plannotator/config.json) includes a short paragraph and an example.

A good round has a few questions about decisions the agent cannot make alone, about 8 at most.

Limits

Share links carry an answer as a comment on the question, not as a filled-in card.
A browser agent using WebMCP tools can read questions and answers but cannot answer.
If the agent rewords a question, your earlier answer is no longer attached to it. The answer shows in the Questions section as unanchored and is still sent.