docs(imsg-skill): document only shipped poll behavior

omarshahine · omarshahine · commit 01e9c38e5cd3 · 2026-07-05T09:55:30.000-07:00
Drop the poll caption echo, --comment override, and inbound question backfill from the imsg skill: those live in imsg PR openclaw/imsg#155, not shipped imsg 0.12.2 (poll --help exposes only --question/--option). Also removes the inaccurate 'reply comment whose reply_to is the poll guid' framing — #155 sends the caption as a plain message, not a reply. Keeps shipped poll send/vote usage. Re-add once a release ships #155.
diff --git a/skills/imsg/SKILL.md b/skills/imsg/SKILL.md
@@ -205,14 +205,11 @@ Use `send-rich --reply-to <message-guid>` for threaded replies. Confirm the refe
 
 Native Apple Messages polls require the bridge. Creation needs at least two `--option` values. Voting requires one of `--option-id`, `--option-index`, or `--option`.
 
-Messages renders only the options on a poll balloon — the poll title is never shown to recipients. So `poll send` automatically echoes `--question` as a reply comment on the poll (a text whose `reply_to` is the poll guid, exactly what the native "comment or Send" field produces). Just set `--question` and the visible caption appears for free — no extra step. Use `--comment` only to make the visible caption differ from the stored title.
+Messages renders only the options on a poll balloon; the `--question` title is not shown to recipients. Set `--question` (required) plus at least two `--option` values.
 
 ```bash
 imsg poll send --chat 'iMessage;-;+15551234567' \
   --question "Dinner?" --option "Pizza" --option "Sushi"
-# --comment overrides the echoed caption when it should differ from --question:
-imsg poll send --chat 'iMessage;-;+15551234567' \
-  --question "Dinner?" --comment "Vote by 5pm 🍽️" --option "Pizza" --option "Sushi"
 imsg poll send --chat 'iMessage;+;chat0000' --reply-to <message-guid> \
   --question "Approve?" --option "Yes" --option "No"
 imsg poll vote --chat 'iMessage;+;chat0000' \
@@ -227,8 +224,6 @@ imsg history --chat-id 42 --limit 20 --json | jq -s '.[] | select(.poll != null)
 
 Poll vote rows are `poll` events, not tapbacks; `watch --reactions` is not required to see them.
 
-Inbound native polls carry no title of their own, so imsg backfills the poll's `question` from its caption (the reply-to-the-poll message) — a native poll read back from history/watch shows the real question, not an empty one.
-
 ## Watch and Long-Running Agents
 
 For a short one-off wait, use `watch`:
