The lessons A to M

Thirteen rules that came from the user's reviews: where each came from, what enforces it and how well it is supported.

The lessons on one page

Grades (from principles.md): A replicated or experimental, narrow scope; B established theory with supporting studies; C craft doctrine, little controlled evidence; D contested or failed replication, do not build on it; Ours our own corpus, small n, hypotheses only.

Where the lessons and our own data disagree

A. No naked data; cognitive load is a budget

Origin. 2026-10-24, review of Moser Baer v3: the script was "cognitively complex"; raw data gives value but only after the viewer has a human reason to care; a number's meaning comes from stakes or contrast. v3 had 41 spoken figures, 6 in the hook and 6 in one 30-second window.

What it requires.

• At most 5 quantities a minute (bar: 3), at most 4 in any 30 seconds, at most 1 figure in the hook.
• At most 7 hero numbers, the figures the argument turns on. Each needs a stake line before it in the same beat and a comparator with it. Everything else is a support figure attached to a hero, or a drop that goes to a graphic or the ledger.
• Four ways to give a number meaning, in the order to try: a prediction then the test; a contrast pair (said and did, plan and outcome); human scale (per person, per rupee, labelled derived); a person on the receiving end.
• Every term of art is glossed at first use, by analogy where possible (Moser Baer: a bond is like a bar tab that only shows up at closing time).

Support. Cowan 2001 (about four chunks at once; debated), Mayer's multimedia principles (grade A for learning tasks, unverified for entertainment), Loewenstein's information-gap work (B). The identifiable-victim effect is grade D (a 2024 replication found no support), so human stakes are a design choice here, not a law.

B. One core driving loop

Origin. 2026-10-24. The openings were good but weak; find the real loop that respects the packaging promise; hint the destination, not the direction; escalate in the first 60 so the video out-delivers its promise. A later remark on v5, a 73-second hook: "too thin". That became B8 and the hook cap of 110 seconds.

What it requires. A declared core driving loop (CDL) chosen from at least three scored candidates; a viewer prior it breaks; a destination hint under 20 words; a withheld list of route terms that must not appear in the hook; the click confirmed with something concrete inside about 30 seconds (75 words); a three-rung promise ladder with each extra promise seeded in the hook and paid later (rung 1 by 60% of runtime, rung 2 between 50% and 90%, rung 3 after 80%); at least one unannounced bonus; the biggest reveal after the midpoint; and, for a hook over about 75 seconds, a named person with a want, the weight of the rise and of the fall, a stake for "you", two forward moments and the learning. Details: page 08.

Support. Loewenstein and Golman (B), Brewer and Lichtenstein's structural-affect theory (B), Hitchcock's bomb under the table (C), a leaked production memo read only through summaries (C). The Zeigarnik effect is grade D and is not cited.

C. BUT / THEREFORE, never "and then"

Origin. 2026-10-24, citing Parker and Stone's rule: if "and then" fits between two sections, the flow is broken. Between beats the link must be a complication (BUT), a consequence (THEREFORE) or an explanation read backwards (BECAUSE).

What it requires. Every junction typed and with a reason; the hinge quote present; no additive opener (and then, next, meanwhile, later, a bare dateline); the next beat picks up a word the last two sentences created; a BUT share between 0.2 and 0.65. Three tests: say "and then" aloud between the beats; swap the beats; check the shared noun. A BUT must reverse an expectation the previous beat planted on purpose. Grade C.

D. Understand, Care, Change, Compel

Origin. 2026-10-24. Show something to understand, make them care why it matters, change what they believe, give them a reason to continue by closing a loop with a bigger one.

What it requires. Each beat declares its four parts with quotes. The care line comes before the beat's first figure. At least 40% of beats care through the viewer or a person. Middle beats run 90 to 260 words. The spine loop opens in the hook and stays open until the last quarter; beat loops close within two beats; at most three loops live at once; no stretch over 60 seconds without a pending beat-level question; the last two sentences of each beat open a question that the next beat answers.

E. A pull for the whole script

Origin. 2026-10-25, v4 review: "an open loop that keeps the viewer watching through might not be satisfied for the full script. It doesn't have to be explicit; it can be subtle, implicit and implied." A beat loop is alive only from the last two sentences of one beat to the next; the middle of a beat had nothing pending.

What it requires. At least four declared pulls of at least three kinds (clock, irony, jeopardy, prediction, motif, gap, pattern). Each is planted early, touched at least twice with real words in the text, and resolved or admitted aloud as a gap. A pull is warm for 60 seconds after a touch. No stretch over 45 seconds with nothing pending (warn; fail at 75). One pull is a person at risk, one a motif that returns at the close. Support: Gerrig and Bernardo (grade A, fiction only), Brewer and Lichtenstein (B), dramatic irony (C).

F. A plain spoken voice

Origin. 2026-10-25, v4 review: "full of ai speak (no x, no y, just a simple z)". v4 measured 5 negation pivots, 18 staged run-ups and 0.47 contractions per 100 words against about 1.5 in English winners.

What it requires. Budgets, not bans: negation pivots at most 1; staged run-ups and script-talk at most 3; stock phrases at most 2; no fragment drumrolls; few triads; not every beat ending on a punch line; sentence-length variation; contractions at least 1.0 per 100 words (the bar says 1.5); no dashes; short sentences. The source catalogue is Wikipedia's "Signs of AI writing" and two public skills; the page itself says humans use these devices too, so they are a checklist for flat prose, not a detector. Grade C.

G. A personality that travels

Origin. 2026-10-25, v5 review: a personality that suits the whole channel; earnest (follows leads, researches, honest about gaps) and aloof (finds negative and positive in all sides, unbiased); using metaphors, similes and parables whenever possible.

What it requires. At least three earnest and three aloof lines, each in at least three beats, from early in the script to its end; contested calls told both ways in the same beat; exactly one governing metaphor, introduced by 45% of runtime, touched at least three times, with its limit stated aloud (the treadmill: "a treadmill has a stop button, a bond with a date doesn't"); at least three glosses by analogy; at least one parable of 25 to 130 words with no figures in it; a budget of 4 to 16 comparisons, at most 2 a minute, few stock figures and verdict words. "Whenever possible" became a budget because the evidence says one early, novel, apt metaphor beats many (Sopory and Dillard 2002, grade B). The persona itself has no experimental support in explainer channels (grade D).

H. Rhythm

Origin. 2026-10-25, v5 review: how hard data insight moments are distributed with the easy storytelling ones.

What it requires. Scripts are cut into 30-second windows. A window is hard when it has two or more quantities. At most 3 hard windows in a row (fail above 6); hard windows at most 40% and quiet windows (no figure) at least 30%; no two consecutive beats at 4 or more quantities a minute; every hero number followed within 45 words by a landing (a person, the viewer or a picture, with no figure); a quiet human close with at most 2 figures. Thresholds were calibrated on 8 English winners (hard share median about 30%, quiet about 46%, longest run median 3) after a first draft of the rule would have flagged 4 of the 8.

I. The human element

Origin. 2026-10-25, v5 review: personifying; finding the personal stake of the viewer or of a character we care about, said to activate mirror neurons. The same review: "So let's start with the city he left." Where does this come from, who is he, why do I care?

What it requires. At least two people declared: a protagonist with a want, a concrete detail and a stake, and a witness who pays; the protagonist named in the hook (within 160 words) and given a want; no hinge line that leans on a pronoun unless the person is named in that sentence or the one before; nobody and no "you" absent for more than 60 seconds (fail at 100); at least three viewer stakes (hook, middle, end); the protagonist across at least four beats and the witness in at least three, early and again in the close. The mirror-neuron explanation of empathy is contested (D), so the design rests on want, detail, stake and presence.

J. Tell the whole story

Origin. 2026-10-25, v4 review: the full story that got truncated in v3 and v4, such as the foundation in Kolkata and all the human and historic nuance. Meeting this by hand left nothing to stop a future script cutting the founder and the rise again, so it became a rule.

What it requires. Each beat declares the part of the story it tells. All of origin, rise, turn, response, fall, people, blame and lesson must have a beat, in a sensible order, with the origin in the first two beats after the hook and the lesson in the last two. A different kind of video sets arc_required. The rule forces planning for completeness; it cannot judge whether a beat is rich. Grade C.

K. Nothing the viewer has to decode

Origin. 2026-10-25, the user's notes on the Hinglish v6: "who is Ratul... constantly appearing new figures", "no one talks like that", "Xidex seems out of place". Five notes were about nobody being told who someone is; six about words nobody says.

What it requires.

• K1, K2 cast tags. Every person gets a role or relation when named ("Ratul Puri, Deepak's son and a company director") and again when they return after 150 words or a beat boundary. The protagonist is exempt after the first tag.
• K3, K4 name rent. At most 5 new people or organisations in a beat; a name that appears once has a declared reason or is cut. (Xidex, a billion-dollar trivia with no documented tie to Moser Baer, was cut.)
• K5 backed counts. A spoken count is a promise (items follow) or a tally (items came before), and the number matches.
• K6 named ideas. Defined once in plain words at first use, then used again (pivot, scale, the treadmill).
• K7 No gloss for what the audience knows (crore, CBI for an Indian business audience).
• K8 No vague referent ("whatever was running out") and no verb buried behind a long aside; use the word people say.

Grade B- for the mechanism (signalling principle, d = 0.38 across 29 learning experiments at abstract level), C for this use.

L. Stakes at the turns

Origin. The same review. "paisa hi paisa kamaya... start with lekin"; "poore 17 saal"; "establish the tension and success".

What it requires. The hook states the prize in the audience's own words and then turns on a contrast word within two sentences (L1: "made serious money doing it. But one morning in November 2017"); the line where the witness pays carries an intensifier ("a full 17 years", "part of their own pay") (L2); every BUT junction is heard, with a contrast word within two sentences either side (L3); no neutrality disclaimer where the record supports a conclusion: aloof about people, plain about mechanisms (L4). In the checklist: the opening list is what the audience actually did (including the slightly guilty association), the hook's last line is a puzzle about a person's act, each beat is a small arc of doubt, edge and proof, the height is restated before the fall point, and a cliffhanger lands in the viewer ("you'd do a double take"), not in an unnamed crowd.

M. Density: a headline first

Origin. The user's own strategy: "sometimes the script can become too dense. A strategy there can be to give a summary of the events to follow in one small line... then use the following lines to fill in the details, close loops, make people care for the human story and stakes."

What it requires. A beat with 7 or more figures or 4 or more new names opens with a headline of at most 20 words within its first two sentences, with no figure in it (M1); the hook ends as a trailer, with a tease of at most 30 words and a takeaway of at most 14 (M2); no lab voice, meaning the narrator does not announce a test (M3).

How a remark becomes a lesson

From references/lesson-protocol.md. Follow it when the user says "this feels like X" about a script, or when a reader finds a defect that a linter scoring 100 missed. Keep the change as small as the lesson needs.

1. Restate the remark as a design constraint, in the user's terms, and write down your reading of any ambiguous phrase.
2. Diagnose the current script against it with counts, not impressions.
3. Research it, and grade each source A to D. Say where the popular claim fails.
4. Ask what our own corpus says, and measure the winners we have. State any tension.
5. Find a deterministic proxy: a declared quote that must occur verbatim, or a pattern counted in the text. Rater agreement on loops and flow was only 0.08 to 0.39, which is why declared quotes are used.
6. Decide integration (inside an existing step, a new step, or a new pass). Prefer one plan and one pass.
7. Calibrate the threshold on winners (calibrate.js), not taste. Record the sample size.
8. Write the damage test before trusting the rule. Then try to pass the rule with a bad script; every loophole becomes a fix and a mutation.
9. Record it everywhere it must live: rules.json, lint.js, selftest.js, principles.md, chain-schema.md, SKILL.md, scaffold.js, learnings.md, the teardown taxonomy.md, the cohort checklist.js if it is to be tested blind, tools.md and history.md.
10. Apply it to the script and report plainly: 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.

When the remarks are margin notes (round 7)

1. Read all the notes as a set before touching anything. Unrelated-looking notes share a cause.
2. For each, write the literal note, the viewer problem behind it, the general lesson (without the topic's names) and the check.
3. Research any claim a note makes about the world before applying it. Four of 35 notes carried claims the sources do not support (Xidex as a partner, "studied this country his whole life", "araam se", "sales doubled").
4. Apply each lesson to every beat, not only the annotated ones.
5. Make the checkable part deterministic, then test the check twice: on the new script (it must pass) and on the old script (it must fail where the reviewer found the defect).
6. Add damage-test mutations, do the read-aloud pass on the result, and record it.

The full trace of all 35 notes and what each became is in references/review-round-7.md.

Written 2026-10-27 from the repository files and the project memory notes. If a page and a file disagree, the file is right: fix the page.