CLAUDE.md

# Project instructions

This repository builds a YouTube production pipeline. Phase 1 is a channel in the Indian business ecosystem with a series "Why X died / The fall of X". The pipeline for **scripts** is documented and automated; start at `docs/SCRIPT-PIPELINE.md`.

## When asked for a video script (new topic, a new version, a revision, a rescoring)

1. Use the `video-script-production` skill (`.claude/skills/video-script-production/SKILL.md`). Read `references/runbook.md` and `references/quality-bar.md`, then follow the eleven stages. Resume with `node .claude/skills/video-script-production/scripts/check.js --dir research/<slug>/script --version vN`; it says which stage the files show and what to do next. Stop at `BAR MET` or when the user says stop, and name the stage reached.
2. Research before prose. Verify the causal link and cross-check every key figure in a second source. Research the person before the company. Besides rival videos (S1), harvest the articles and primary documents that already exist (S1b: `scripts/fetch-articles.mjs`, Google AI Mode as a link finder; `references/research-protocol.md` section 7; worked example `research/the-fall-of-videocon/`).
3. Never edit `scripts/rules.json` to make a script pass. If data contradicts a rule twice, change the number and record the reason in `references/learnings.md`.
4. Say plainly what is unproven. The lessons are design constraints, not findings; a linter score of 100 means the declared structure matches the text.

## When asked to make, rebuild, edit or check a video (a beat of the video, "the video", scenes, visuals, sound effects) or to apply the user's notes on one

1. Use the `video-visual-production` skill (`.claude/skills/video-visual-production/SKILL.md`). Read `references/runbook.md` and follow it step by step; it is written so that a small model can run it. The worked example is beat B1 of Moser Baer v7 Hinglish (`research/the-fall-of-moser-baer/video/beat-sheet-B1.json`; run the proof with `node .claude/skills/video-visual-production/scripts/smoke-b1.js`).
2. For the user's notes on a built video follow `references/edit-guide.md`: map each note to a scene id (from `REVIEW-<beat>.md`), change the beat sheet with `edit.js` (snapshotted, linted, logged, reverted if it breaks a gate), rebuild once; only changed scenes re-render. Never regenerate the beat sheet or edit the output.
3. You cannot watch or hear the video. Never say it is good; report what was measured (`STATUS-video-<beat>.md`), what you saw in stills (contact sheet), and what only the user can judge.
4. Articles and typeset text on screen are approved by the user; broadcaster video, logos, private people's faces, stock and invented pictures are not. Why: `research/video-production/04-other-areas.md` and `06-real-footage-and-youtube.md`. Only ledger facts with status `V`, `V-1source`, `derived` or `analysis` may be drawn.
5. The plan, research and build spec for the whole video stage are in `research/video-production/` (start at `README.md`).
6. To produce several beats at once ("B2 to B5 in parallel") use the `video-beats-orchestrate` skill: Haiku sub-agents for three stages (`video-beat-prepare`, `video-beat-storyboard`, `video-beat-build`; `video-beat-review` exists but is off by default: the user dropped reviews on 2026-11-01 and accepts first-pass mistakes; the user chose Haiku everywhere to save tokens, made safe by the compact plan format and compose-beat.js). The user asked for these sub-agents; do not spawn others.
7. To join the beats into one video (transitions, score, one mix) run `scripts/stitch.js` of the same skill; steps in the last section of `references/runbook.md`; the joins and the music are edited in `research/<topic>/video/score-spec.json`. The score is synthesised and has not been heard by anyone; the report lists what only the user can judge.

## Standing rules from the user

- Do not commit or push unless asked. Do not spawn subagents unless asked (the blind-reader pass needs them; leave it as a decision for the user).
- 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 for this pipeline, **add or update its row in `.claude/skills/video-script-production/references/tools.md` in the same session**, and one line in `references/history.md` if it changed the process. The user wants these recorded.
- After each script, append what it taught to `references/learnings.md` ([method], [measure], [content]) and write the research record with `scripts/session-log.js`.
- "First 60 mins" in the user's feedback means the first 60 seconds. State assumptions like this in the hand-off.

## Practical notes

- Windows with Git Bash and PowerShell. Node scripts only; no dependencies in the skill.
- **Shell heredocs and `sed` swallow backslashes** (a `\b` in a regex became a backspace character, twice). Write code and regexes with the Write or Edit tool. `check.js` scans for stray control characters.
- Dates in notes are the user's local day (IST). The session transcript stores UTC, 5 h 30 min earlier.
- `transcripts/`, `reports/` and `data/` are gitignored; the cohort ledger lives there and is local. `research/` is tracked.
- Memory notes for this project are in the Claude memory folder; `reference_script-pipeline-docs` points here.
- When the user annotates a script with margin notes or line edits, follow `.claude/skills/video-script-production/references/review-round-7.md` (cluster the notes, find the viewer problem behind each, check the claims, apply to every beat, make the checkable part deterministic). A note is a request for an effect on the viewer, not a source.