docs/SCRIPT-PIPELINE.md

# The script pipeline: from a topic to a script at the v6 bar

**Status (2026-10-25).** Built across five rounds of feedback on one video (Moser Baer). It reached v6, which the user approved. Everything needed to run it again on another topic is written down and, where it can be, automated. It has **not yet been run on a second topic**, so "reaches the v6 bar in one go" is the design intent, not a result. The first run on a new topic is the test; record what it teaches in `learnings.md`.

This page is the front door. The detail lives in the skill: `.claude/skills/video-script-production/`.

## What it does

Takes a topic ("the fall of X") and produces `SCRIPT-vN.md` (packaging, spine, voice-over, fact ledger, open items), `chain-vN.json` (the script's structure, declared as quotes that must occur in the text), a gate report and a hand-off, to a defined quality bar. The structure is **declared and checked mechanically** so the user's lessons are enforced, not remembered. What a machine cannot judge (does a care line land, is the narrator likeable, does the hook hold people) is covered by a read-aloud checklist and, when the user authorises subagents, blind readers.

## Run it

To have a fresh session run everything for a topic, paste the prompt in `.claude/skills/video-script-production/references/launch-prompt.md` (filled in for Cafe Coffee Day; six fields change per topic).


```
# 1. scaffold (once per topic; --from vM for the next version)
node .claude/skills/video-script-production/scripts/scaffold.js --dir research/<slug>/script --version v1 --beats 13 --title "<working title>"

# 2. work through the runbook, then at the end of every stage:
node .claude/skills/video-script-production/scripts/check.js --dir research/<slug>/script --version v1 [--prev v0] [--fix] [--no-selftest]
```

`check.js` prints `HARD GATES FAILING`, `HARD GATES PASS, BAR NOT YET MET` or `BAR MET`, and writes `STATUS-vN.md`. Read `references/runbook.md` for the eleven stages and `references/quality-bar.md` for what "finished" means.

## The stages and what runs them

```
S0 set up ........ scaffold.js
S1 rival brief ... src/topic-research/cli.js           (LLM; names and numbers are leads, not facts)
S2 rival teardown  skill winning-video-teardown        (Sonnet analysts; skip if the series teardown covers it)
S3 fact base ..... web research -> FACTS.md            (references/research-protocol.md)
S4 thesis ........ references/opening-protocol.md      (core driving loop, packaging, title tension)
S5 chain + plan .. chain-vN.json                       (beats, pulls, cast, persona, figures, hook elements)
S6 draft ......... SCRIPT-vN.md section 3              (hook last)
S7 two passes .... texture pass (adds), voice pass (subtracts)
S8 gate loop ..... check.js; references/lint-fixes.md  (lint 70 rules, damage test 56, ledger, timecodes, bar)
S9 read-aloud .... extract-vo.js; read-aloud-checklist.md
S10 readers ...... reader-prompts.md                   (only if the user asks for subagents)
S11 hand-off ..... HANDOFF-vN.md; handoff-template.md; session-log.js
```

## The thirteen lessons (A to M)

Each began as a remark by the user on a draft; each is a rule in `lint.js` with a damage test. Evidence grades and limits: `references/principles.md`, `texture.md`.

| | Lesson | Where it came from |
|---|---|---|
| A | No naked data; cognitive load is a budget | v3 review: "cognitively complex... a human reason to care for the data" |
| B | One core driving loop; destination without direction; a promise that out-delivers; a hook that carries weight | v3 review; v6 review ("the hook is thin") |
| C | BUT / THEREFORE, never "and then" | v3 review (Parker and Stone's rule, which the user cited) |
| D | Understand, care, change, compel | v3 review |
| E | A pull for the whole script, even implied | v4 review: "an open loop... can be subtle and implicit" |
| F | A plain spoken voice, no machine tells | v4 review: "full of ai speak (no x, no y, just a simple z)" |
| G | A personality: earnest and aloof; one governing metaphor, glosses, a parable | v5 review: "personality... earnest... aloof... metaphors, similes, parables" |
| H | Rhythm: hard and easy moments; a landing after every number | v5 review: "how we distribute hard/data insight moments with the easy storytelling ones" |
| I | The human element: protagonist, witness, the viewer | v5 review: "personifying... the personal stake" and "who is he, why do I care" |
| J | Tell the whole story | v4 review: "the full story that got truncated in v3 and v4" |
| K | Nothing the viewer has to decode: cast tags, a named idea defined once, backed counts, plain words | Hinglish v6 review: "who is Ratul... constantly appearing new figures", "no one talks like that", "Xidex seems out of place" |
| L | Stakes at the turns: the prize in the audience's words, a spoken contrast, the cost, a doubt-edge-proof arc, a cliffhanger in the viewer | Hinglish v6 review: "paisa hi paisa kamaya... start with lekin", "poore 17 saal", "establish the tension and success" |
| M | Density: a one-line headline before the details; a trailer hook; no lab voice | Hinglish v6 review: "sometimes the script can become too dense... give a summary of the events to follow in one small line" |

## The version ladder (Moser Baer)

| | v3 | v4 | v5 | v6 | v7 |
|---|---|---|---|---|---|
| Length | 9.5 min | 12.8 | 17.3 | 19.6 | 20.2 |
| Rules passed | (no chain) | 28 | 37 | 55 | 70 |
| Damage tests | n/a | 15 | 24 | 42 | 56 |
| Quantities per minute (in the hook) | 4.3 (6) | 1.7 (0) | 2.3 (0) | 2.0 (1) | 2.0 (1) |
| Contractions per 100 words | n/a | 0.47 | 1.12 | 1.84 | 1.65 |
| Hook | list-style | 74 s | 73 s | 110 s, carries a person, the rise, the fall | 107 s, a 24-word tease and a 13-word takeaway |
| Added | | stakes, one loop, a chain, a beat contract | pulls, plain voice, the whole story | personality, rhythm, the human element | cast tags, a defined idea, spoken turns, headlines on dense beats (a polish, not a rebuild) |

`references/history.md` has the full account of each round.

## Other languages

A finished English script can be turned into Hinglish (or another language) without re-running the pipeline: `references/hinglish-adaptation.md` has the rules, `scripts/hinglish-parity.js` checks that the facts and the structure survived, and `scripts/tts-gemini.js` builds the per-beat Gemini TTS prompts (English or Hinglish) from the script and a small spec of where the tags go. `lint.js` and the chain are English-anchored and do not apply to the Hinglish text.

## What is proven and what is not

- **Proven:** the linter, the damage test and the gate runner behave as designed on Moser Baer v4 to v6 and on blank and copied scaffolds. The ledger check found real gaps in v5 and v6.
- **Not proven:** that any lesson improves performance. None of A to M has been tested on viewers or in a cohort of weak and strong scripts. In the earlier cohort test, blind script craft did not predict performance among winners. The winners we measured use few figures of speech and almost no first-person admissions, which v6 does on purpose.
- **Not run:** a blind-reader pass on v5 or v6; a second-topic run of the runbook.
- **Design budgets, not findings:** every threshold in `rules.json`, calibrated on at most 8 winner transcripts.

## Where things are

| | Path |
|---|---|
| The skill (entry point `SKILL.md`) | `.claude/skills/video-script-production/` |
| Runbook, quality bar, history, research log, protocols, checklists, prompts, tool registry | `.claude/skills/video-script-production/references/` |
| Tools | `.claude/skills/video-script-production/scripts/` (`check.js`, `lint.js`, `selftest.js`, `ledger-check.js`, `retime.js`, `extract-vo.js`, `calibrate.js`, `session-log.js`, `compare.js`, `scaffold.js`; data in `rules.json`, `voice-patterns.json`) |
| The approved script, its chain and gate report | `.claude/skills/video-script-production/examples/moser-baer-v6/` |
| The live Moser Baer files | `research/the-fall-of-moser-baer/` |
| Sibling skills | `.claude/skills/winning-video-teardown/`, `script-cohort-analysis/`, `within-channel-study/`, `ecosystem-rater/` |
| Upstream tools | `src/topic-research/`, `src/series-analysis/`, `README-SERIES-ANALYSIS.md` |
| Standing instructions for any session | `CLAUDE.md` |

## Keeping it alive

1. After every script, add what it taught to `references/learnings.md` and run `session-log.js`.
2. When you create a skill or tool for this pipeline, add its row to `references/tools.md` in the same session.
3. When a review comment becomes a lesson, follow `references/lesson-protocol.md` (ten steps and the files to touch).
4. When new winners arrive, run `calibrate.js` and update thresholds with the reasons recorded.
5. The next steps, in order of value: run the whole runbook on a second topic; add the E to J checks to the cohort rubric; add a named-people-and-terms density rule; run readers on v6.