Plan Comments And Feedback

---
name: plan-comments-and-feedback
description: >-
  Plan review threads end to end: what `get-plan-feedback` returns, how to read
  anchors, resolver intent, replies, notification email, deletion, and abuse
  reports. Use when reading, answering, resolving, or removing plan feedback.
---

# Plan Comments and Feedback

- Plan comments include reviewer identity, @mentions, resolver intent
  (`agent` or `human`), exact anchors, and design-review threads. When adding
  human feedback through `update-visual-plan`, preserve `authorEmail` and
  `authorName` when known; pass `parentCommentId` to reply inline to an
  existing comment thread. Text feedback should anchor to the nearest prose
  block, and visual/canvas feedback should include target coordinates plus
  concise surrounding context.
- Use `delete-plan-comment` only when the user explicitly asks to remove a
  comment, undo an accidental comment, or clean up an obsolete thread. Deleting
  is a soft delete: normal comment views hide the comment while the database row
  remains for audit/debugging. Deleting a thread root also deletes its replies.
  When feedback has merely been handled, prefer `resolve-plan-comment` and
  `consume-plan-feedback` so review history remains visible.
- Use `delete-visual-plan` only when the owner explicitly asks to delete or
  restore their hosted plan/recap data. `mode=soft` moves the resource to the
  Deleted tab and makes normal reads/direct links stop working; `mode=restore`
  undeletes it; `mode=hard` permanently removes the plan row plus plan-scoped
  comments, sections, events, versions, shares, reports, SQL asset records, and
  collab snapshots. Hard delete requires the exact confirmation phrase
  `DELETE <planId>`.
- `get-plan-feedback` returns flat comments, grouped threads, anchor summaries,
  detailed anchor lines, and recent review events that describe the edit/comment
  delta. Use those fields before changing code or updating the plan, especially
  to distinguish comments the agent should act on from comments intended for a
  human reviewer.
- **Anchor interpretation.** `targetX`/`targetY` are percentages within the
  named element; bare `x`/`y` are percentages of the whole document;
  `canvasX`/`canvasY` are board-world pixels. Wireframe anchors carry
  `targetNodeId`/`targetNodePath` — prefer those over raw coordinates; fall back
  to coordinates plus the focused screenshot only when no node id is present.
  Resolve `textQuote` with `contextBefore`/`contextAfter`; if `ambiguous: true`,
  ask the user. Threads in `detachedThreads` no longer match current prose —
  reconcile, never drop. Act on `resolutionTarget=agent`; treat `human` as
  context only; `@mentions` are notification signals, not routing. Mark ingested
  comments consumed (`consumedCommentIds`); set `status=resolved` only on
  agent-targeted comments you actually addressed. When a plan write addresses
  feedback, do not resolve or consume it until a post-write `get-visual-plan`
  confirms the requested change persisted. Then do both: call
  `resolve-plan-comment` for the addressed thread and `consume-plan-feedback`
  for its comments.
- New human comments send best-effort transactional email when email is
  configured: root comments and replies notify the plan owner, @mentioned
  members, and replies also notify prior human participants in that thread.
  Reuse the shared `renderEmail` template; do not invent a separate
  plan-specific email style.
- `report-visual-plan` records a bounded abuse report for a public plan or recap
  without changing plan content. It requires the caller to be scoped to an
  accessible public plan, accepts a fixed reason plus optional short details,
  and updates an existing open report from the same reporter instead of creating
  duplicate rows.

## Related Skills

- **plan-hosted-writes** — verify a write persisted before resolving or
  consuming the feedback it addressed.
- **plan-browser-editing** — the editing surfaces reviewers annotate.
- **plan-source-sync** — `comments.json` sidecars for DB-free local plans.
- **plan-events** — automating notifications on `plan.commented`.