commit 76b20f6d1ca68bdf9509dd3b2cf83aecf2e23fe3
parent ac75077edc3893d0689fbc66853f3591d9f7be49
Author: I Mean I'm Just Saying <imeanimjustsaying@kiwifarms.st>
Date: Sat, 19 Sep 2026 02:24:54 -0400
docs: two verdicts, an optional note, and how you listen
report-video.md's `verdict` section becomes a table: confirmed takes an
optional note, incorrect requires one, absent means nobody has looked — plus
the legacy reading and why the required-note rule is keyed on the explicit
value. clip-bench.md gets the same in the walk's own words, the edge-aware
audition, and the two per-browser playback preferences.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Diffstat:
2 files changed, 60 insertions(+), 26 deletions(-)
diff --git a/umtool/docs/clip-bench.md b/umtool/docs/clip-bench.md
@@ -154,13 +154,18 @@ answer.
<kbd>y</kbd> confirms and **advances**, because in the yes case the next clip is
what you want and a walk of sixty clips should be one finger. <kbd>x</kbd> puts
-the cursor in the `correction` box, because the note *is* the no answer — and it
-stays put, because the note is the work. The state reads back inline:
-*confirmed*, *corrected*, or *not yet reviewed*, and the header counts how much
-of the cut has been reviewed.
-
-Stored as `verdict: "confirmed"` / an absent key, mutually exclusive with
-`correction` — see [report-video.md](report-video.md#verdict--whether-anybody-has-looked).
+the cursor in the `correction` box and marks it **required**, because the note
+*is* the no answer — and saving it stays put, so it can be read back against the
+clip. That save is ONE patch, `{correction, verdict: "incorrect"}`, so the
+manifest never holds a complaint with no verdict.
+
+A note on a clip that is already **confirmed** is just a note — why its window
+moved, a caveat for the writers — and writing one there leaves the verdict
+alone. The state line reads *not yet reviewed*, *confirmed*, *confirmed · with
+note* or *incorrect*, and the header counts how much of the cut has been
+reviewed. See
+[report-video.md](report-video.md#verdict--what-the-walk-said) for what is
+stored and what the writer refuses.
## The cue rail
@@ -173,11 +178,25 @@ cannot disagree). Clicking a cue snaps the nearer edge to it.
## Keyboard
`[` `]` move the start · `,` `.` move the end · shift for 0.5 s instead of 0.05 ·
-`space` auditions the selection · `R` resets to the saved window.
+`space` auditions the whole selection · `R` resets to the saved window ·
+`p` `n` walk · `y` confirm · `x` note what is wrong · `-` `=` playback speed ·
+`a` auto-audition.
Audition happens on pointer-**up**, never during a drag — the Deck's rule, because
a sound restarting on every `pointermove` is unusable.
+**A move auditions the edge that moved.** Every change used to play the first
+six seconds, so nudging the end — the edge that decides whether a clip stops
+mid-thought — played the start and answered a question nobody asked. A moved end
+plays the four seconds *ending* on it; a moved start plays the four after it.
+
+**Playback speed and auto-audition are per browser**, in `localStorage`
+(`umtool.bench.playback`), never in the manifest: how fast somebody listens is a
+fact about the person at the desk. The speed applies to the rendered-segment
+player too. Auto-audition is off by default and, when on, plays a clip once on
+arrival — after `canplay`, not racing it, because a `play()` before the element
+is ready is a silent no-op that reads as a broken option.
+
## Saving
`PUT /api/report/window` with `{project, clip, start, end, lock…, title, date,
diff --git a/umtool/docs/report-video.md b/umtool/docs/report-video.md
@@ -47,7 +47,7 @@ travel. umtool never reorders as a side effect of a window edit.
"date": "2016-09-12", // optional: overrides the record's upload date
"note": "…", // why it is in the cut (editorial, for humans)
"correction": "…", // what the REPORT got wrong here; never rendered
- "verdict": "confirmed", // the walk looked at this clip and agreed; absent = unreviewed
+ "verdict": "confirmed", // or "incorrect"; absent = nobody has looked yet
"chapter": "…", // chapter title; falls back to date + title
"section": 2, "sectionEnter": true,
"lock": true, "lockStart": true, "lockEnd": true }
@@ -121,37 +121,52 @@ the one definition; the project page lists it and `umtool corrections <project>`
prints the same list as markdown with the QR's own moment link per bullet, ready
to paste into the next prompt.
-### `verdict` — whether anybody has looked
+### `verdict` — what the walk said
-`"confirmed"`, or **absent**. Never rendered, like `correction`, and written by
-the same three writers (the clip bench's `y`, `PUT /api/report/window`,
-`umtool window --verdict confirmed`). An empty value deletes the key.
+`"confirmed"`, `"incorrect"`, or **absent**. Never rendered, like `correction`,
+and written by the same three writers (the clip bench's `y` and `x`,
+`PUT /api/report/window`, `umtool window --verdict confirmed|incorrect`). An
+empty value deletes the key.
A clip is a *claim*: the report said somebody said this, here. Walking the cut
-is somebody checking that claim against the audio, and it has exactly two
-answers — so there are three states out of two keys:
+is somebody checking that claim against the audio.
-| on disk | state |
-|---|---|
-| `correction` non-empty | **corrected** — the "no" answer IS the note |
-| `verdict: "confirmed"` | **confirmed** |
-| neither | **not yet reviewed** |
+| on disk | state | `correction` |
+|---|---|---|
+| `verdict: "confirmed"` | **confirmed** | optional — a *note* |
+| `verdict: "incorrect"` | **incorrect** | **required** |
+| neither | **not yet reviewed** | — |
+
+**The note is not always a complaint.** On a confirmed clip `correction` says
+why a good clip's window moved, or something a reader should know; on an
+incorrect one it says what the report got wrong. `umtool corrections` and the
+project page split on the *verdict*, not on "has text", so the next pass is
+never sent to fix a clip nobody complained about.
+
+**An incorrect verdict with no note is a complaint nobody can act on**, so the
+writer refuses it. The rule is a property of the entry *after* the patch, which
+makes both halves one check: setting `incorrect` with no note, and clearing the
+note off a clip that is already `incorrect`, are the same error and get the
+same sentence — *"an incorrect verdict needs its note: say what the report got
+wrong"*. The bench sends `{correction, verdict: "incorrect"}` as one patch for
+exactly that reason.
**An absent key is the point.** A manifest nobody has walked says so by carrying
nothing, rather than by carrying `"verdict": "unreviewed"` on sixty entries —
which reads like a decision and would have to be written before the walk could
start.
-**A clip cannot be both**, and `updateClip()` keeps it that way rather than
-asking every reader to pick a winner: writing a non-empty `correction` drops a
-stale confirmation, and confirming a clip that still carries one is refused with
-"clear it first if the description is actually accurate".
+**Legacy is read, not migrated.** A clip carrying a `correction` and no
+`verdict` was written before `incorrect` existed and means exactly that:
+`clipVerdict()` reads it as **incorrect**. The required-note rule is keyed on
+the explicit value, so those entries can still be cleared — a rule that refused
+to let somebody undo a note they wrote before the rule existed would be a trap.
`reviewOf()` is the one definition of coverage — the bench header's
`N reviewed`, the project page's "Walk the cut" button and `umtool corrections
<project>` all read it, and the last opens with
-`N clips: A corrected, B confirmed, C not yet reviewed (ids: …)` so the walk's
-coverage is visible beside the defects it found.
+`N clips: A incorrect, B confirmed (C with a note), D not yet reviewed (ids: …)`
+so the walk's coverage is visible beside the defects it found.
A card entry is `{"type":"card", "id", "style", "seconds", …}` — see the pipeline
README for the styles. Cards have no window and no source.
