.claude/skills/video-script-production/references/lesson-protocol.md

# How a review comment becomes a lesson (the protocol that produced A to M)

Every rule in this pipeline began as one of the user's remarks on a draft. The same ten steps turned each remark into something the linter enforces and the next script inherits. Follow them when the user says "this feels like X" about a script, or when a reader finds a defect the linter scored 100. Keep the change as small as the lesson needs; the user has said twice that they like the current direction and want changes "subtle".

| # | Step | What it looked like (examples) |
|---|---|---|
| 1 | **Restate the remark as a design constraint**, in one sentence, in the user's terms, and write down your reading of any ambiguous phrase | "No naked data; a number's meaning comes from stakes or contrast" (A). "first 60 mins" read as the first 60 seconds (assumption stated in the hand-off). "AI speak" read as negation pivots, staged run-ups and unspoken written English (F) |
| 2 | **Diagnose the current script against it with counts**, not impressions | v3 had 41 spoken figures, 6 in the hook, 6 in one 30-second window and two signpost joins; v4 had 5 negation pivots, 18 staged run-ups and 0.47 contractions per 100 words |
| 3 | **Research it**, with an eye to what is contested. Grade each source A (replicated, close to our case), B, C (craft or contested), D (do not rely on it). Say where the popular claim fails | Zeigarnik replicates inconsistently; the identifiable-victim effect is near zero in the largest studies; mirror neurons as a mechanism of empathy are contested. They are graded C or D and not cited as proof (`principles.md`, `texture.md`) |
| 4 | **Ask what our own corpus says**, and measure the winners we have | S-ANALOGY 9 of 20 and S-PERSONA 6 of 20: the winners do not need the devices the user asked for. State the tension; do not hide it (`texture.md`) |
| 5 | **Find a deterministic proxy**: something declared in the chain and verified against the text, or a pattern counted in the text. Prefer declared quotes that must occur verbatim (rater agreement on loops and flow was only 0.08 to 0.39) | stake line before the hero number (A6); the junction hinge quotes (C4); pulls with touches (E1); the cast with a want and a stake (I1); a landing after each hero number (H4) |
| 6 | **Decide integration**: new rules inside an existing step, a new step, or a new pass. Ask whether the new work would rewrite the last. Prefer one plan and one pass | E and F went in as small additions (a pull inventory; a voice pass). G, H and I went in as one texture plan (in the chain) and one additive pass, ahead of the subtractive voice pass |
| 7 | **Calibrate the threshold on data**, not taste. Run `calibrate.js` on the winners; set the warn at the winners' median and the fail beyond what most winners did; record the sample size | the hard-window run limit was drafted at 2 and moved to 3 after it would have flagged 4 of 8 winners; the floor on contractions is a design choice above the winners' median and is labelled as one |
| 8 | **Write the damage test for the rule before trusting it**: a mutation that breaks exactly that property, and check the rule fires. Then try to pass the rule with a bad script; every loophole found becomes a fix and a mutation | the dangling-pronoun rule was passed by a name from three paragraphs earlier; a role phrase counted as naming; the parable test looked only at the first and last line. All three were caught by the mutation for I2/I3/G3 |
| 9 | **Record it everywhere it must live**: `rules.json` (the number and its reason), `lint.js` (the rule), `selftest.js` (the mutation), `principles.md` (the lesson, its grade, what it does not prove), `chain-schema.md` (the fields), `SKILL.md` (the table row and the step), `scaffold.js` (the template), `learnings.md` (what the work taught), the teardown `taxonomy.md` (so winners are counted for it), the cohort rubric `checklist.js` if it is to be tested blind, `tools.md` and `history.md` | see each lesson's row in `history.md` |
| 10 | **Apply it to the script and report plainly**: say what the linter proves and what it does not, what was an assumption, which numbers are design budgets, and what was found wrong in earlier versions | every hand-off message in this project |

## When the remarks arrive as margin notes (round 7)

The ten steps above fit one remark at a time. A reviewer who writes thirty-five notes inside the text needs a step before them: **cluster the notes, then find the viewer problem behind each**, because notes that look unrelated often share a cause (five were about nobody being told who someone is; six about words nobody says; four about a turn that was not spoken). `review-round-7.md` section 1 is the method and section 2 is the worked trace of every note: what it said, the intent assumed, the lesson, the rule, where it was applied. Three habits from that round: (1) a note is a request for an effect on the viewer, not a source: four notes carried claims the sources did not support, and each was checked before it was applied (Xidex, the "studied his whole life" edge, the anti-dumping outcome, "sales doubled"); (2) apply each lesson to every beat, not only the annotated ones; (3) run each new rule on the old script as well as the new one, because a rule that does not flag the defect the reviewer found is not the rule they meant.

## Rules of thumb that held

- A passing linter is not a finished script. Both readers and the read-aloud pass found problems at 100/100 (dense paragraphs of names and terms, an oversold tease, a vague referent). Keep the judgement gates.
- When a rule and the story collide, fix the story first; change the rule only when data contradicts it twice, and write why.
- A rule you cannot damage-test is a wish. Every rule has a mutation, or a recorded reason why it cannot.
- Tell the user when a lesson conflicts with the corpus (the cold open on the collapse did worse in earlier cohorts; the winners use few figures of speech). They decide; the ledger tests it later.
- Rules about voice are budgets, not bans. Humans use every device; the problem is density and repetition.
- When you build a tool by hand twice, promote it into `scripts/` and add it to `tools.md` (the calibration, the retiming and the research log were all scratch scripts before they were tools).
- When a rule needs a declaration, an undeclared chain should warn and a wrong declaration should fail, so scripts written before the rule still pass the hard gates (round 7 did this for K, L, M).
- Small, graded steps: an interim version that is better than the last is worth recording before the next lesson arrives.

## The files a new lesson touches (checklist)

```
scripts/rules.json          threshold and reason
scripts/lint.js             the rule(s), a lesson name
scripts/selftest.js         at least one mutation per rule
scripts/voice-patterns.json patterns, if text-level
scripts/scaffold.js         template fields
scripts/check.js            only if it changes the bar (rules.json "bar")
references/principles.md    the lesson, its grade, its limits
references/chain-schema.md  fields and the table of checks
references/<topic>.md       the reasoning and the evidence (texture.md, voice.md, implicit-pull.md)
references/lint-fixes.md    what the rule usually means
references/learnings.md     [method] / [measure] / [content] bullets with the date
references/history.md       one row in the timeline
references/tools.md         any tool or skill created
SKILL.md                    table row, step, description
../winning-video-teardown/references/taxonomy.md   mechanisms to count in winners
../script-cohort-analysis/scripts/checklist.js     the blind check (rubric version bump)
```