.claude/skills/video-script-production/SKILL.md

---
name: video-script-production
description: Take a topic (or a research brief, a verified fact base and a winners teardown) to a finished YouTube explainer script at the Moser Baer v6 bar - title/thumbnail promise, core driving loop, beat-by-beat voice-over, fact ledger - and prove it with a one-command gate runner. Encodes thirteen lessons (A to M) from the user's reviews - stakes before data and a load budget, one core loop with a destination hint and a promise that out-delivers, a BUT/THEREFORE chain, the Understand-Care-Change-Compel beat contract, implied pulls between the questions, a plain spoken voice with no machine tells, a personality that is earnest about facts and aloof about verdicts with one governing metaphor, glosses by analogy and a parable, an alternation of hard and easy moments with a landing after every number, a human element (a protagonist with a want, a witness who pays, the viewer spoken to), the whole story told, nothing the viewer has to decode (every person tagged where they arrive and return, a named idea defined once, counts backed by items, plain words), stakes at the turns (the prize in the audience's words, a spoken contrast, the cost of a sacrifice, a doubt-edge-proof arc), and a one-line headline before the details of a dense beat. Includes a runbook, a deterministic linter (70 rules), a damage test, a gate runner, a ledger check, a retimer, a calibration tool, a session logger, a scaffold, a Hinglish parity check, a Gemini TTS prompt builder, a worked example and the full build history. Use when the user asks to write, revise, rescore or improve a video script, to produce the next video in the series, or after a winning-video-teardown when the next step is the script. Not for testing which script rule predicts performance (script-cohort-analysis) or for analysing existing winners (winning-video-teardown).
---

# Video script production

## Start here

The pipeline that produced Moser Baer v6 (the script the user approved) is written down so it can run again on another topic. **Read `references/runbook.md` and `references/quality-bar.md` first.** The runbook has eleven stages from "a topic" to a hand-off; the quality bar says what "finished" means. Then:

```
node .claude/skills/video-script-production/scripts/scaffold.js --dir research/<slug>/script --version v1 --beats 13 --title "<working title>"
node .claude/skills/video-script-production/scripts/check.js   --dir research/<slug>/script --version v1 [--prev v0] [--fix] [--no-selftest]
```

`check.js` runs every automatable gate, reads the manual gates from `HANDOFF-vN.md`, says which stage the files show you have reached, writes `STATUS-vN.md` and prints what to do next. **Run it first when you resume work and last before you stop.** Stop at `BAR MET`, or when the user tells you to (then name the rung you reached: `runbook.md` section 3).

Ground rules (each came from the user): research before prose; say plainly what is unproven; no subagents, commits or pushes unless asked; keep the user's direction and change as little as a lesson needs; never edit `rules.json` to make a script pass. See `runbook.md` section 0 and the defaults in section 1.

## What this is

The stage between "we understand why other videos work" and "here is the script". It turns a **verified** fact base into a script whose structure is declared up front and checked by a linter, so the lessons from earlier reviews are enforced, not remembered.

```
topic ─> src/topic-research (rival brief) ─> winning-video-teardown ─┐
                                                                      v
web research ─> FACTS.md ─> CDL + thesis ─> chain + texture plan ─> voice-over ─> texture pass ─> voice pass
                                                                      │
              check.js (lint, damage test, ledger, timecodes, bar) <──┘ loop
                                  │
                  read-aloud pass ─> (blind readers, if authorised) ─> hand-off ─> film
```

## The lessons

From the Moser Baer v3 review (2026-10-24: A to D), the v4 review (2026-10-25: E and F, and the request to tell the whole story, which became J) the v5 review (2026-10-25: G, H, I) and the line-by-line review of the Hinglish v6 (2026-10-25: K, L, M; `references/review-round-7.md` traces every note to its rule). `references/principles.md` grades the evidence for each and says where our own corpus pushes back; `references/texture.md` has the reasoning for G, H, I; `references/history.md` says how each arrived.

| | Lesson | Enforced by |
|---|---|---|
| **A** | No naked data. Raw data needs a human reason to care first; its meaning comes from stakes or contrast. Cognitive load is a budget. | hero-number budget, stake line before each hero number, 4 quantities per 30 s, jargon glossed at first use |
| **B** | Find the one core driving loop that respects the packaging promise. Hint the destination, not the direction. Escalate in the first 60 seconds so the video visibly out-delivers its promise. A longer hook must carry weight. | declared CDL, withheld list, first payoff inside 30 s, three-rung promise ladder, unannounced bonus, hook elements (B8) |
| **C** | Each section follows from the last by BUT or THEREFORE, never "and then". | typed junctions, hinge quotes, additive-opener check, shared-noun test |
| **D** | Understand, then care, then change what they believe, then compel: close a loop by opening a bigger one. | four-step beat declaration, loop ledger, forced-continuation check |
| **E** | The loop that keeps people watching can be implied. Something should be pending for the whole script. | declared pulls (clock, irony, jeopardy, prediction, motif, gap, pattern), each touched in the text; no stretch over 45 s with nothing pending |
| **F** | It should sound like a person talking, not like machine prose ("no X, no Y, just Z"). | budgets on negation pivots, staged run-ups, stock phrases, drumroll rhythm; contractions and sentence variation |
| **G** | A personality that suits the whole channel: earnest about facts and people, aloof about verdicts; it explains with one governing metaphor, glosses by analogy and a parable. | both registers early and late, contested calls told both ways, one governing metaphor that returns and states its own limit, a budget on comparisons, stock figures and verdict words |
| **H** | Rhythm: hard data moments alternate with easy story moments, and a number lands on a person or a picture. | 30-second hard and quiet windows, no wall of numbers, a declared landing after every hero number, a quiet human close |
| **I** | The human element: a protagonist with a want, a witness who pays, and the viewer spoken to. | people declared and found, protagonist named in the hook, no pronoun without a name at a hinge, no minute without a person or "you", viewer stakes in the hook, middle and close |
| **J** | Tell the whole story (the founder, the place, the partner, the rise, the turn, the response, the fall, the people, the blame question, the lesson), not a truncated one. | each beat declares the story part it tells; all required parts present, origin early, lesson last |
| **K** | Nothing the viewer has to decode: every person is tagged where they arrive and where they return; every name earns its place; counts are backed by items; a named idea is defined once and reused; no gloss for what the audience knows; plain, concrete, speakable words. | cast tags (K1, K2), name load and one-off names (K3, K4), counted sets (K5), concepts (K6), audience terms (K7), vague referents and buried verbs (K8) |
| **L** | Stakes at the turns: the prize in the audience's own words and then a spoken contrast; an intensifier where a person pays; a doubt, an edge and a proof in each beat; plain about mechanisms the record supports; a cliffhanger that lands in the viewer. | hook prize then contrast (L1), witness cost intensifier (L2), every BUT spoken (L3), no neutrality disclaimer on a supported mechanism (L4); checklist 20 to 25 |
| **M** | Density: a dense beat opens with a one-line headline (no figure in it), then the details; the hook ends as a trailer, not a menu; the narrator does not announce a test. | headline on dense beats (M1), tease and takeaway length (M2), no lab voice (M3) |

Scripts live in `scripts/` (Node, no dependencies). `S` below means `node "<skill dir>/scripts/...`. `references/tools.md` is the registry of every skill and tool in the pipeline; **add a row there whenever you create or change one.**

## The steps (and the runbook stages they belong to)

| Step | Runbook stage | |
|---|---|---|
| 0 | S0 | the lessons gate |
| 1 | S3 | facts first |
| 2 | S4 | the core driving loop |
| 3 | S5 | the chain and the texture plan |
| 4 | S6 | write the voice-over |
| 4a, 4b, 4c | S7 | the texture pass (adds), the voice pass (subtracts), the clarity pass (cast, terms, turns, headlines) |
| 5 | S8 | lint and iterate (`check.js`) |
| 6 | S9, S10 | the read-aloud pass; blind readers (if authorised) |
| 7 | S11 | hand-off |

### Step 0: the lessons gate (mandatory)

1. Read `references/learnings.md` and apply its [method] and [measure] points. Its [content] points are hypotheses.
2. Read `scripts/rules.json`: those thresholds are the current definition of the lessons. If a cohort has contradicted a rule twice, change the number there and record why in `learnings.md`; never edit the linter to get one script through.
3. After the final step, append what this script taught as [method], [measure] or [content] bullets with the project name.

### Step 1: facts first

Follow `references/research-protocol.md`; the template is `FACTS.md` from `scaffold.js`.

- Build the fact base before any prose. Every figure carries a status: `[V]` verified against a non-YouTube source, `[V-search]` seen only in a search summary, `[CHECK]` unverified, `derived` (with the arithmetic), `analysis` (flagged aloud). Rival-video claims that cannot be verified go in a "do not use" table.
- **Verify the causal claim, not just the numbers.** The Moser Baer v4 draft first said "the bond turned the decline into a debt"; the fact check then found the 2004 expansion was already debt-funded and no source says where the bond's money went. The thesis changed. List every "X caused Y" and find a source for the link itself.
- **Research the person before the company.** Two founder profiles that were never opened turned the story from a bond into a man who always left what was running out.
- **Cross-check the magnitude of every key figure in a second source.**
- For each fact note its stake: whose loss, which belief of the viewer's, which contrast.
- Prefer primary or near-primary sources. Single-source anecdotes about private individuals stay out unless on the record in a national outlet.

### Step 2: find the core driving loop

Follow `references/opening-protocol.md`, steps 1 to 5: packaging question, viewer priors, 3 to 5 scored candidates, choice, check against the title. Record the candidates in `chain.cdl.candidates`. If the title promises more than the evidence supports, say so to the user and offer title options that match; do not quietly shade the script.

### Step 3: build the chain before the prose

1. List the beats as one-line statements with an `arc` tag each (origin, rise, turn, response, fall, people, blame, lesson), then type every junction THEREFORE, BUT or BECAUSE, with a `link_why` (for a BUT: the expectation the previous beat planted).
2. Run the three junction tests in `references/beat-contract.md` (say-it-aloud, swap, shared noun).
3. For each beat fill Understand / Care / Change / Compel. If Change is empty the beat is information, not progress: merge or cut.
4. Choose hero numbers (at most 7) with stake lines and landings; push everything else to graphics or the ledger (`references/stakes-and-load.md`).
5. Draft the promise ladder and one unannounced bonus; the peak reveal goes after the midpoint.
6. **Pull inventory** (`references/implicit-pull.md`): for every minute of runtime write what the viewer is waiting for right now. Declare at least four pulls of at least three kinds in `chain.pulls`, one of them a person, one a motif that returns at the close. Plant early, touch at least twice, resolve or admit the gap aloud.
7. **Texture plan** (`references/texture.md`): for every beat one line: opening move (person, scene, viewer or parable) · claim · number and its landing · figure · earnest or aloof lines. Declare the cast (`humans`: a protagonist with a want, a witness who pays, a counterpart), the viewer's stakes, the persona lines and sides, the one governing metaphor with its stated limit, the glosses and a parable, and the hook elements. The plan is the chain; there is no separate document.

8. **Clarity plan** (`references/principles.md` K, L, M; `chain-schema.md`): give every person `tags` (the role or relation to say where they arrive and return) and, for the witness, a `cost_quote`; declare `audience.known_terms`, each spoken count in `counted_sets`, each named idea in `concepts`, each name that will appear once in `one_off_names` with its reason (or cut it); mark the dense beats and write each a `headline_quote`; add `turn_quote`, `tease_quote` and `takeaway_quote` to `cdl.hook_elements`.

`S/scaffold.js` writes the blank script, chain, `FACTS.md` and `HANDOFF-vN.md` (or the next version with `--from`).

### Step 4: write the voice-over

- Beat by beat in the contract order, **hook last**. One `**VO:**` line per paragraph; graphics in italic parentheses; no citations inside the voice-over (they go in the ledger).
- The care line comes before the beat's first figure. Say a hinge sentence, not a signpost ("Here is the second number I promised" is a list, not a link).
- Name the central idea once and reuse the name. Gloss every term of art at first use, by analogy. Use `derived` figures only with the arithmetic in the ledger.
- Open a beat on a person or a picture, then the claim, then the number, then a landing (a person, the viewer or a picture with no figure in it). Name a person before any "he" or "she". Speak to "you" in the hook, the middle and the close. Use one governing metaphor, return to it, and say where it stops working; gloss hard words by analogy; give a parable with no figures in it. Be earnest about facts and people, aloof about verdicts and heroes.
- Write it to be said. Contractions where people use them, sentences you can say in one breath, no staged announcements ("Here is what matters"), no denial of something nobody said before the point ("It was not X. It was Y."). State the point.
- Hedge what you cannot show, in the voice-over ("I have not found where that money went"). Honest gaps build trust and protect the claim. Every "I" must be true of whoever records it.
- `examples/moser-baer-v6/` shows how each chain field appears in the text.

### Step 4a: the texture pass (additive)

After the draft, before the voice pass, read once for each question in `references/texture.md` (who is in every beat and what do they want; where is "you"; what lands after each number; any run of more than two number-heavy 30-second stretches; does the governing metaphor return and state its limit; an earnest and an aloof line in each third; is every "I" true; does any "he" or "she" at a hinge have a name in the same or the previous sentence). This pass **adds** words. Run the voice pass next, which **removes** the tells they may bring: *add, then subtract, then lint.*

### Step 4b: the voice pass

Read the whole script aloud at speaking pace and follow `references/voice.md` (mark, rewrite by pattern, specificity test, keep the honest hedges, do not over-correct). It is built from the Wikipedia *Signs of AI writing* catalogue and two public skills (humanizer, stop-slop). It changes how the script sounds, never what it claims; no fact enters that is not in the ledger.

### Step 4c: the clarity pass

After the voice pass, read each beat once for the K, L, M questions (`read-aloud-checklist.md` items 1 to 3 and 20 to 26): who is a stranger here, what has to be decoded, is the turn spoken, where is the cost said, does a dense beat open with a headline, does the hook end as a trailer. Add the headline last, once the details are final. Then lint.

### Step 5: lint and iterate

```
S/check.js --dir <scriptDir> --version vN [--prev vM] [--fix] [--no-selftest]   # everything below, plus a status report
S/lint.js --script <SCRIPT-vN.md> --chain <chain-vN.json> --label vN --out <dir>
S/selftest.js --script <SCRIPT-vN.md> --chain <chain-vN.json>                  # damage test: each rule fires when broken
S/ledger-check.js --script <SCRIPT-vN.md> --chain <chain-vN.json> [--facts FACTS.md] --strict
S/retime.js --script <SCRIPT-vN.md> --write                                    # heading time ranges from word counts
S/compare.js --a <lint-vA.json> --b <lint-vB.json> --sa <A.md> --sb <B.md> --out <compare.md>
```

- Fix every FAIL in the script, not in `rules.json`. Read every WARN; the heuristic ones (naked numbers, shared noun, negation pivots) can be false alarms, but decide, do not skip. `references/lint-fixes.md` lists what each rule usually means and the fix that worked.
- Run `selftest.js` after changing the linter or `rules.json`, to confirm the rules still fire.
- A score of 100 means the *declared structure* is sound and consistent with the text. It does not mean the script is good (Step 6).

### Step 6: test with readers who did not write it

The linter cannot see whether a care line lands, whether a BUT truly reverses an expectation, whether a persona is likeable, or where a person would stop watching.

- **The read-aloud pass (S9, always):** `S/extract-vo.js --mode timed`, then `references/read-aloud-checklist.md`. Record the result in `HANDOFF-vN.md`.
- **Fresh-reader pass (S10, only when the user has asked for subagents):** `references/reader-prompts.md` has the prompts (a first-time viewer and a skeptical editor, with the texture questions). Give each only the blind text from `S/extract-vo.js --mode blind`. Compare with the declared chain; each disagreement is a defect in the script, not in the reader.
- **Statistical check** (when there are enough comparable scripts): `script-cohort-analysis` with rubric v3 (it does not yet include the E to M checks; `references/tools.md` gap 1).
- Log what the readers found in `references/learnings.md`.

### Step 7: hand-off

Deliver `SCRIPT-vN.md`, `chain-vN.json`, `HANDOFF-vN.md`, `lint/`, `STATUS-vN.md`, the open-items list (every `[CHECK]` and `[V-search]`), and a plain statement of what is unproven: the lessons are design constraints, not findings, and the title/evidence tension if there is one. Message structure: `references/handoff-template.md`. Then `S/session-log.js` for the research record, update `learnings.md` and `tools.md`, and stop. Do not commit or push unless asked.

## Reference index

| File | What it holds |
|---|---|
| `references/runbook.md` | the eleven stages from topic to hand-off, defaults, the maturity ladder |
| `references/quality-bar.md` | the v6 bar: gates, judgement checks, the reference profile |
| `references/history.md` | how v3 became v6: each round, what was said, researched, built, found |
| `references/research-log.md` | every search and fetch behind v4 to v6, by phase, and what each was for |
| `references/research-log-round7.md` | the searches and fetches behind v7 (the Hinglish review): anti-dumping, profits, floppy rank, sales, the signalling evidence |
| `references/s1-rival-brief.md` | S1 in full: the YouTube search, captions, extraction and synthesis tool; how to read its output into the fact base; failure modes |
| `references/research-protocol.md` section 7 | S1b: harvest existing articles, orders and filings with `scripts/fetch-articles.mjs`; Google AI Mode as a link finder; the dated `TIMELINE-AND-TRIVIA.md` |
| `references/s2-teardown.md` | S2 in full: choosing rival videos, the teardown steps and options, the synthesis template, the genre baseline |
| `references/research-protocol.md` | how the fact base is built and verified |
| `references/lesson-protocol.md` | how a review comment becomes a rule (and the files a new lesson touches) |
| `references/principles.md` | lessons A to M, evidence grades, what this does not prove |
| `references/review-round-7.md` | how 35 line-level notes became lessons K, L, M: the method, every note and what it became, what the research found, what was built |
| `references/hinglish-adaptation.md` | turning a finished English script into Hinglish: the rules, the parity check, the TTS prompts |
| `references/texture.md` | G, H, I: the reasoning, the evidence table, the integration decision |
| `references/implicit-pull.md`, `voice.md`, `stakes-and-load.md`, `beat-contract.md`, `opening-protocol.md` | the detail behind E, F, A, C/D, B |
| `references/chain-schema.md` | the script markers and every chain field, and what the linter checks |
| `references/lint-fixes.md` | each rule's usual cause and fix |
| `references/read-aloud-checklist.md`, `reader-prompts.md` | the judgement gates |
| `references/handoff-template.md` | the final message and the hand-off file |
| `references/launch-prompt.md` | the prompt that makes a fresh session (even a small model) run the whole pipeline for one topic; filled in for Cafe Coffee Day |
| `references/tools.md` | registry of skills and tools, with the known gaps |
| `references/learnings.md` | what each script taught ([method] / [measure] / [content]) |
| `examples/moser-baer-v6/` | the approved script, its chain, its gate report, and a map of the form |
| `examples/moser-baer-v7/` | the polish after the Hinglish review: the English and Hinglish scripts, the chain with the K, L, M fields, the TTS spec, the gate report |

## Why it is built this way

- **Declared structure, checked mechanically.** Earlier rater-based measures of loops and flow were unreliable (agreement 0.08 to 0.39). When the author declares loops, hinges, stake lines, people and figures as quotes, they can be verified without anyone's judgment. The price is that a declaration can be gamed; the damage test, the read-aloud pass and the readers are the checks on that.
- **Lessons as data.** Thresholds live in `rules.json` and reasons live in `principles.md`, so a new lesson is one rule and one paragraph, and a contradicted lesson is one number.
- **Honesty about evidence.** The principles file grades its sources. The pipeline's job is to make the lessons cheap to follow and cheap to test, not to claim they are proven.
- **One plan, one additive pass, then the subtractive pass.** New texture lessons were integrated into the chain and one pass, not three sequential rewrites (`texture.md`).

## Extending

Follow `references/lesson-protocol.md` (ten steps and the list of files a new lesson touches). In short: a rule in `scripts/lint.js` under its letter, its threshold and reason in `rules.json`, a mutation in `scripts/selftest.js`, a paragraph and grade in `references/principles.md`, the matching check in `script-cohort-analysis/scripts/checklist.js`, a mechanism in `winning-video-teardown/references/taxonomy.md`, a row in `references/history.md` and `references/tools.md`. New language: the quantity detector and connective lists are English; add the language's number words and additive markers to `rules.json` and `lint.js`.