docs(transcript-fixer): the reviewer's decision_note is an instruction, and nothing promotes it

[daymade]

The gap

A reviewer overrode a suggestion and attached the reason — a rule about a whole class of substitutions, worth far more than the single edit it rode in on. The edit was recorded; the rule reached nothing, and the next session re-flagged the same class.

The tooling was working correctly the entire time:

dashboard 备注 box (app.js:160) → /api/resolve → CLI --note → decision_note (review_queue.py:668)
                                                                    ↓
                                       commands.py:1652 prints it — but only when status != pending

SKILL.md taught agents how to write that column and never once how to read it, let alone promote it. This skill's whole premise is that corrections compound; an explanation that stays in decision_note is the one kind of knowledge here that provably does not.

What the section adds

• Where the note hides — the human-readable --show-review gates it behind status != pending, while --json carries the key unconditionally. Since the agent path here is --json, it was always reachable.
• Which verdicts to sweep — kept_original specifically. A "this class is deliberate, stop flagging it" note lands on exactly that verdict, and the status filter used by the neighbouring text-propagation sweep (accepted|overridden) misses every one of them.
• Routing by what the note says — a four-row table, because the exits are not interchangeable and the obvious-looking one is backwards: for "stop flagging this", --add is the exact opposite — it creates a rule that rewrites the text from then on.

Independent review found two real defects in the first draft

Both on one sentence. The sharper one: the exit I had pointed at — the append_note action — runs only on accept and is dropped by design on overridden (SKILL.md:258-260), which is precisely the verdict the motivating example used. Readers were being sent to an exit the system discards in the exact scenario described.

Also fixed: a false universal ("a verdicted item is the only place the note exists" — _reopen writes the note while sending the item back to pending, review_queue.py:708), the --show-review/--json precision, and the missing kept_original command. 7/7 findings adopted.

Five other candidates were dropped by verify-first

The local plugin cache is 1.16.2, 128 lines behind source, and the source already covers them — including One verdict fixes one occurrence (SKILL.md:333), which documents the exact residue I had just measured, with better data than I had. Without that check this PR would have shipped a duplicate.

Gates

Gate	Result
quick_validate	Skill is valid
Regression audit	0 candidates / 2669 exact preservations (pure addition)
security_scan	passed + manual Layer-4 read-through (its keyword pass cannot see CJK names or verbatim transcript lines)
Version	daymade-audio 1.18.0 → 1.18.1

scripts/ deliberately untouched — a parallel session is actively working cli/ and core/ there.

🤖 Generated with Claude Code