.claude/skills/winning-video-teardown/SKILL.md

---
name: winning-video-teardown
description: Take a set of YouTube videos that performed very well and work out, for each one, what it does well and exactly how it achieves the effect, in both the script (open loops, narrative, psychology, pacing) and the packaging (title and thumbnail promise, information gap, hidden-world and information-asymmetry promises, whether the video earns them). Produces a quoted per-video teardown plus counts of which mechanisms recur. Use when the user wants to understand WHY good videos work, to extract the moves and patterns of winners, or to teach a creator what to copy, rather than to test statistically which script rule predicts performance (that is script-cohort-analysis).
---

# Winning video teardown

## What this is

A close reading of videos already known to have worked. For each video an analyst reads the whole transcript, looks at the thumbnail, and explains what the video does well and how, naming the mechanism and quoting the exact moment. Then the skill counts which mechanisms recur across videos.

This is qualitative craft analysis, not an experiment. It cannot tell you that a mechanism *caused* the performance (the videos are all winners, there is no comparison group, and the analysts know they are reading winners). What it gives you is a grounded vocabulary of moves, each tied to quoted evidence, that you can reuse and later test (for example in a script-cohort-analysis run that includes weak videos).

## Inputs

Folders of transcript `.txt` files in the standard layout (sections `=== VIDEO ===`, `=== PERFORMANCE ===`, `=== CHANNEL ===`, `=== TRANSCRIPT ===`, with `[mm:ss]` paragraphs). The series-analysis `cohorts` stage writes exactly this. Scripts below are in `scripts/` (Node, no dependencies); `S` means `node "<skill dir>/scripts/...`.

## Procedure

1. **Prepare.** `node S/prepare.js --cohort <dir> [--cohort <dir2> ...] --out <runDir>`
   Builds `cases/Vxx/` (metadata and transcript), downloads each thumbnail to `thumbs/`, and writes one task file per video in `tasks/`.
2. **Analyse, one subagent per video.** Spawn `general-purpose` subagents with `model: "sonnet"` (qualitative reading of Hindi and English captions needs more than Haiku). At most 20 run at once; launch in batches and refill as they finish. Every subagent gets exactly this prompt:
   > Read the task file `<task path>` and follow it exactly. Read only the files it lists. Finish with one line: output path + validator result.
3. **Validate.** The validator runs inside each analyst's task, and you can re-run it: `node S/validate.js --file <analysis.json> --case <caseDir>`. It checks structure, that every mechanism id is in `references/taxonomy.md`, that the analysis has enough mechanisms and evidence, and that at least 85% of the quoted passages literally occur in the transcript. Re-run any analysis that fails with a fresh subagent.
4. **Aggregate and assemble.** `node S/aggregate.js --run <runDir>` writes `aggregate.md/json` (mechanism counts by group, loop statistics, promise-delivery tallies, mechanisms the analysts proposed that the taxonomy lacks). `node S/report.js --run <runDir>` writes `teardowns.md` (one readable section per video).
5. **Synthesise (the only step where you write prose).** Read the aggregate and a sample of teardowns against their transcripts. Write the catalogue of why videos work (script) and why packaging works, using the counts for prevalence and the quoted examples for illustration. Rules:
   - Report prevalence honestly ("in 14 of 20", not "always"). A mechanism present in nearly every video is table stakes, not a differentiator, and you should say so.
   - Spot-check at least five analyst claims by reading the transcript yourself; drop or downgrade any that the text does not support.
   - Fold the analysts' `new_mechanisms` into the taxonomy when two or more analysts independently found the same thing; otherwise report them as single observations.
   - Say what the method cannot show: causation, thumbnails' click-through, audience, retention.

## Why it is built this way

- **Quotes are checked.** The commonest failure of this kind of analysis is plausible-sounding mechanisms that the video does not actually contain. The validator rejects an analysis whose quotes are not in the transcript.
- **A vocabulary, not a checklist.** `taxonomy.md` gives analysts shared names so counts across videos mean something, but they tag only what they can quote, and they can propose new mechanisms.
- **Thumbnails are actually looked at.** Packaging analysis from the title alone misses half the story.
- **Weak points are required.** An analyst that cannot name a weakness is flattering the video.

## Lessons from the first run (20 "Why X died" winners)

- A loose category inflates counts: the first run tagged expectation reversal in 19 of 20 videos because the genre's peak-to-collapse turn matched it. The taxonomy now excludes that case; check any mechanism found in nearly every video for the same problem.
- Quote verification worked: all 20 analyses passed with at most 2 unverified quotes each, and six hand spot-checks of analyst claims against the transcripts all held. Interpretations are still one reader's.
- A pilot of one analyst before launching the rest caught nothing, but it is cheap insurance; keep it.
- Frequent mechanisms are table stakes for the genre, not explanations of why one winner beat another. Say so in the synthesis.

## Revision 2026-10-24: flow, stakes and forced continuation (from the Moser Baer script review)

The review of the first Moser Baer script (v3) set four lessons: figures need a stake before them and a load budget; one core driving loop with a destination hint and a promise that out-delivers; section joins are BUT/THEREFORE, never "and then"; every stretch ends on a question its own answer created. This skill now measures those in the videos it studies, so the next script is written against what winners actually do, not only against the lessons:

- `taxonomy.md` has ten new script mechanisms (S-STAKE-ANCHOR, S-HUMAN-SCALE, S-PREDICT-TEST, S-LOAD-CONTROL, S-HINGE-BUT, S-HINGE-THEREFORE, S-FORCED-HANDOFF, S-DEST-HINT, S-PROMISE-LADDER, S-FIRST-PAYOFF) and a section D defining junction types. A follow-up (2026-10-25) added S-IMPLICIT-PULL (a date, person, motif or gap kept pending without a question) and S-PLAIN-VOICE, from the v4 review; the next teardown run should tag them in winners. A second follow-up (2026-10-25, from the v5 review) added S-LANDING, S-PARABLE and S-TWO-SIDED. The existing S-ANALOGY, S-PERSONA, S-PROTAGONIST, S-SELF-REF and S-SCENE already cover the rest of the personality and human-element lessons; in the first 20 teardowns S-ANALOGY was 9/20 and S-PERSONA 6/20, so presence of these is not what separated the winners.
- `schema.md` adds `script.junctions` (every boundary typed THEREFORE / BUT / AND_THEN / NEW_TOPIC with a quoted hinge), `script.numbers` (how each hero figure was framed, naked examples, densest 30 seconds, load note) and hook fields (`first_payoff_sec`, `figures_in_first_60s`, `destination_hint`, `extra_promises`).
- `validate.js` reports the new fields as warnings, or as errors with `--strict 1`; `prepare.js` now writes `--strict 1` into every task, so new runs must fill them in. Old analyses stay valid and are not rewritten.
- `aggregate.js` and `report.js` add the junction mix, how many videos have no AND_THEN junction, the opening's first-payoff time and figure count, extra-promise payoff rate and figure framing.
- **Treat the first run under the new schema as exploratory.** Whether winners show fewer AND_THEN junctions, more anchored figures or paid extra promises is unknown. If they do not, that is evidence against the lessons (record it in `video-script-production/references/learnings.md` and in the `script-cohort-analysis` ledger); if they do, it is only presence in winners, with no weak comparison group.
- Next stage: the findings feed `video-script-production`, which turns them into a script and checks it with a linter.

## Extending

Add mechanisms to `references/taxonomy.md` (keep the `**ID** - Name.` format; the validator and aggregator read it). Add fields to `references/schema.md` and the checks in `scripts/validate.js` together.