# Design note — polls

**Dated 2026-08-05. Written before the code, per the provenance practice in
[ROADMAP.md](../../ROADMAP.md#proving-independence).**

---

## The job to be done

"Which of these should we do?" is one of the things a forum is *for*, and
Convoro has no way to ask it. The workaround — everybody replies with a
number and somebody counts by hand — is the thing polls were invented to stop.

## Decision 1 — a poll belongs to a topic, not to itself

It is asked inside a conversation, the conversation is where the argument
happens, and a poll with no thread attached is a survey tool.

So: one poll per topic, added when the topic is started or by a moderator
afterwards. Not a separate section, not its own permission model.

## Decision 2 — the vote is a row per choice, and that shapes everything

`poll_votes(poll_id, option_id, user_id)` with a unique key across all three.

Multiple choice falls out for free — it is several rows. Changing a vote is a
delete and an insert. Counting is a `GROUP BY`. And "has this person voted"
is one query whatever the poll's shape.

The alternative — a votes column on each option — cannot answer "who voted for
this", cannot stop double voting, and cannot be corrected when a vote is
withdrawn.

## Decision 3 — a vote can be changed while the poll is open

Somebody who misclicks should not be stuck with it, and somebody persuaded by
the thread should be able to say so. That is the whole point of running the
poll inside the conversation.

Once it closes, the record stops moving.

## Decision 4 — the author chooses whether votes are public

**Public**: the poll shows who voted for what. **Anonymous**: only totals.

Chosen when the poll is made and **never changeable afterwards**, in either
direction. Turning an anonymous poll public would publish something people
were told would be private; turning a public poll anonymous would rewrite what
readers were shown. Both are worse than making the author decide up front.

## Decision 5 — results can be hidden until you vote, but never after the close

A poll that shows the running total influences the running total. Hiding it
until somebody votes is a real option and it belongs to the author.

Once the poll closes, results are visible to everybody regardless, including
people who never voted. A closed poll nobody can see the result of is a
conversation with a hole in it.

## Decision 6 — guests see it, and cannot vote

The result is part of the discussion, so it renders for everybody. Voting needs
an account, because a vote you cannot attribute is a vote you cannot deduplicate.

## Decision 7 — closing is a date or a moderator, and deleting is not editing

A poll can carry a close date, or be closed by hand by its author or a
moderator. A closed poll keeps its votes.

Editing a poll's **options** after votes exist is not offered. Changing the
question people answered invalidates their answers, and silently reassigning
votes to a renamed option is worse. A moderator who genuinely needs to start
again deletes the poll, which takes the votes with it and says so first.

## What this does not do

- **No ranked or weighted voting.** A different feature with a different
  counting story and a much more complicated result to display.
- **No per-group vote weighting or restrictions.** If somebody can read the
  topic, they can vote in it.
- **No poll-only listing or search.** A poll is part of a topic; the topic is
  what gets found.
- **No editing options after the first vote.** See decision 7.
