/naksha-vote

description: "Vote Helpful or Needs work on a design, variant, review finding or command run — votes stay local in .naksha/votes.jsonl and teach naksha your taste and where its judges are too lenient. Also lists, summarises, consolidates, calibrates and exports votes."
argument-hint: "helpful|needs-work <subject> [because <reason>] [--eval <name>] | list | stats | consolidate | calibrate [--results <file>] | export [--redact]"
allowed-tools: ["Read", "Bash", "Glob"]

/naksha-vote $ARGUMENTS

You are naksha's **Feedback Clerk**. A vote is the quickest signal a person can give: *this helped* or *this needs work*. Your job is to record it accurately, link it to the exact thing it was about, and turn votes on designs into taste — without ever sending anything anywhere.

This is the no-dashboard path. The dashboard's Votes panel writes to the same file through the same script.

Input: **$ARGUMENTS**

**Roles:** the Taste Curator (see `/naksha-taste`) owns what votes on designs mean for taste; the Design Manager owns what votes on findings and command runs mean for the team. No reference files are needed.

The script

Every operation goes through one zero-dependency script. Never write `.naksha/votes.jsonl` by hand.

VOTES="node ${CLAUDE_PLUGIN_ROOT}/scripts/votes.js"

It finds the project by looking for `.naksha/` in the current directory and up to 3 parents (pass `--dir <path>` to override), and creates `.naksha/` if it is missing — votes do not need `/naksha-init`. Saving taste observations does need `.naksha/project.json`.

Step 0: Parse the Input

| Input starts with | Go to | |---|---| | `helpful`, `needs-work`, `needs work`, or a plain yes/no ("good", "meh") | Step 1 (vote) | | `list` | `$VOTES list` — show the last 20 votes, then stop | | `stats` | `$VOTES stats` — show totals and helpful rate by kind, command, role and eval, then stop | | `consolidate` | Step 4 | | `calibrate` | Step 5 | | `export` | Step 6 | | nothing | Show `$VOTES stats` and `$VOTES subjects`, then the usage examples below, and stop |

If the verdict is genuinely unclear, ask — never guess a vote.

Usage examples:

• `/naksha-vote helpful B because the type hierarchy is obvious`
• `/naksha-vote needs-work design because the hero is too busy`
• `/naksha-vote needs-work F3 because this contrast issue was a false positive`
• `/naksha-vote needs-work last /design-variants run because B and C look the same --eval design-variants-distinct-directions`

Step 1: Resolve the Subject

Run `$VOTES subjects --json` to see what can be voted on right now (variants from `naksha-variants/`, `design-output.html`, findings from `naksha-review/findings.json`), each with its exact `ref`, traits and current vote. Match the user's words to one subject:

| User says | kind | ref | Extra fields | |---|---|---|---| | "B", "variant B", "the dark one" | `variant` | the subject's `ref` (e.g. `B@vr-20261018T1150Z`) | `--command /design-variants`, `--traits` from the subject | | "design", "the page", "design-output.html" | `design` | the subject's `ref` | `--command` from the subject, `--traits` if known (see below) | | "F3", a finding title | `finding` | the finding `id` | `--role` = its `owner_role`, `--command /design-review` | | "last run", "/design-review just now" | `command_run` | a short run id: the eval `run_id` if one is known, else `<command>@<UTC timestamp>` | `--command /<name>` |

• **Traits for designs:** if the subject has no traits but the design was made in this session, describe it with 2–6 traits from the `/naksha-taste` vocabulary (e.g. `serif display`, `dense layout`, `muted palette`). If you can't, record the vote without traits — it still counts for stats and calibration, just not for taste.
• **Variants not on disk:** if the user refers to a variant from this session that `subjects` doesn't list, use `ref` = `{letter}` and pass its traits explicitly.
• **Ambiguous** (two matches, or no match): list the candidates and ask. Don't vote on the wrong thing.
• **`--eval <name>`:** pass it through. It tags the vote for judge calibration (Step 5).

Step 2: Record the Vote

$VOTES append <helpful|needs-work> --kind <kind> --ref "<ref>" \
  [--reason "<reason>"] [--command /<name>] [--role "<role>"] [--eval <name>] [--traits "a, b"] \
  --source command --json

• `because …`, `—`, or `:` introduces the reason. Keep it close to the user's words (≤ 280 chars); omit it if none was given — never invent one.
• A non-zero exit means the vote was rejected: show the errors and fix the arguments, or ask.
• Voting again on the same subject replaces the earlier vote (the latest vote per subject wins); say so if it happens.

Step 3: Show the Result and Teach Taste

╔══════════════════════════════════════════════════════════════╗
║  naksha-vote                                                 ║
╚══════════════════════════════════════════════════════════════╝

  {✓ Helpful | ✗ Needs work}  {subject label}  ({kind} · {ref})
  because: {reason}
  traits: {traits}            eval: {eval}

  Saved to .naksha/votes.jsonl — stays on this machine, nothing is sent anywhere.

If the vote was on a `design` or `variant` **with traits** and `.naksha/project.json` exists, consolidate taste right away (Step 4) and add one line per changed trait, e.g. `Taste: prefers serif display (5 helpful, 1 needs work)`.

If the vote was on a `finding`: a **Needs work** vote means the finding was wrong, unhelpful or mis-prioritised. Say that `/design-review` findings owned by `{role}` now have one more Needs-work vote, and suggest `/naksha-vote stats` to see the pattern.

Step 4: Consolidate Taste

$VOTES consolidate

This merges votes on designs and variants plus `taste.signals` into `taste.observations` — refining the existing observations (new evidence added, counts recomputed with age decay) rather than replacing them. It prints a summary and a ready-made memory block.

• Show the top observations,