Start here

The map of the project, how to resume work in a new chat, and the rules every session follows.

What this repository is

A single creator is building a YouTube channel and wants the production process written down and automated, so that a new topic can be taken from an idea to a finished script (and then a voice-over and a video) with the same quality each time, without the author in the room. The code does the parts that have a right answer (searching, counting, checking quotes, linting). Language models do the parts that need reading (extracting claims from transcripts, analysing a video). The human decides what only a human can: the topic, the title, whether to name a private person, whether to run extra readers, and whether to commit.

The work happened in this order, and the docs follow it:

The pages

The three marked core in the side list are the ones the user asked to be most thorough: how a series is researched, how a topic is chosen, and how a script is written and checked.

Which pages to read, by job

Resuming in a new chat window

1. Read CLAUDE.md at the repo root. It is loaded automatically in Claude Code and holds the standing rules.
2. Find where a script stands. From the repo root:

   node .claude/skills/video-script-production/scripts/check.js --dir research/the-fall-of-moser-baer/script --version v7 --no-selftest

   It prints one of HARD GATES FAILING, HARD GATES PASS, BAR NOT YET MET or BAR MET, names the stage the files show, and says what to do next. It also writes STATUS-vN.md.
3. Read Status and open items and the script's HANDOFF-vN.md for the decisions that are waiting.
4. Check git status and git log. Most work is uncommitted; do not assume a clean tree.
5. Do not guess a procedure. The runbook is .claude/skills/video-script-production/references/runbook.md; this site summarises it and links to it.

Standing rules from the user

• Do not commit or push unless asked.
• Do not spawn subagents unless asked. The blind-reader pass and option A of the teardown need them, so both are left as a decision for the user.
• Research before prose. Verify the causal link, cross-check every key figure in a second source, research the person before the company.
• Never edit scripts/rules.json to make a script pass. Fix the script. Change a number only when data contradicts a rule twice, and record why in references/learnings.md.
• Say plainly what is unproven. A lint score of 100 means the declared structure matches the text; it does not mean the script is good.
• Keep the user's direction. When they say they like the current approach, change as little as a new lesson needs.
• When you create or change a skill or a deterministic tool, add its row to references/tools.md in the same session, and a line to references/history.md if it changed the process.
• After each script, append what it taught to references/learnings.md and write the research record with scripts/session-log.js.
• Write code and regexes with the Write or Edit tool. Shell heredocs and sed swallow backslashes (it happened three times).
• "First 60 mins" in the user's feedback means the first 60 seconds. State assumptions like this in the hand-off.
• When the user annotates a script with margin notes, a note is a request for an effect on the viewer, not a source. Find the problem behind each note, check any claim in it, apply the fix to every beat (references/review-round-7.md).
• Use they/them for people whose pronouns are not stated.

Glossary

Ecosystem / niche

A subject area on YouTube, such as Indian business. Each has its own SQLite database in data/.

Series

A repeatable video format, defined by a spec in series/<id>.json. Here: Why X died and The fall of X.

Topic

One subject for one video, such as Moser Baer or Cafe Coffee Day. Its folder is research/the-fall-of-<slug>/.

Cohort

A fixed set of transcripts picked by a rule, to be studied together. Here: 10 new and 10 established "Why X died" winners.

Teardown

A close reading of a video: what it does, how, with a quoted moment for each claim. Done by language-model analysts and checked by a validator.

Beat

One section of the script, 40 to 105 seconds. B0 is the hook; the last beat is the close. Each follows Understand, Care, Change, Compel.

Hook

Beat B0, the first 60 to 110 seconds.

CDL

Core driving loop: the one question the video exists to answer.

Chain

chain-vN.json: the script's structure declared as quotes that must occur in the text, so a linter can check it.

Hero number

A figure the argument turns on. At most 7 per video, each with a stake line before it and a landing after it.

Pull

Something the viewer is waiting for without being asked a question: a clock, a person at risk, a gap, a motif.

Ledger

The section of the script file listing every figure with its source and status.

[V], [V-search], [CHECK]

Fact status. [V] a non-YouTube page was opened and read. [V-search] seen only in a search summary. [CHECK] unverified. Also derived (with arithmetic) and analysis (reasoning the voice-over must flag).

Gate

A check a script must pass. Hard gates decide the exit code; bar gates decide BAR MET.

Damage test

selftest.js: breaks a script one property at a time and checks the matching lint rule fires. It tests the linter, not the script.

S0 to S11

The eleven stages of the runbook, from setting up a folder to the hand-off.

v6 bar

The quality bar set from Moser Baer v6, the script the user approved ("i like v6").

Hinglish

Hindi grammar with English words, written in Roman script.

TTS

Text to speech. Here: Google Gemini TTS, one audio file per beat.

HinExp

A YouTube channel the series is modelled on; it is the reference channel in the series spec.

Keeping these pages current

These pages are static HTML with a shared stylesheet at assets/docs.css. The side list is copied into every page, so adding a page means adding one list item to each. The existing Markdown files in this folder (SCRIPT-PIPELINE.md, PROMPT-cafe-coffee-day.md, google_ai_search_automation_thread.md) are older and stay as they are. The single source of truth for the script pipeline is the skill folder; when you change a rule, a threshold or a stage there, update 06, 07 or 09 in the same session, in the way CLAUDE.md already asks for tools.md.

Every number on these pages was read from a repository file on 2026-10-27. Numbers that come from a plan or an estimate are labelled as such. Where the repository does not record something (for example why the Indian business niche was chosen), the page says so instead of filling the gap.

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.