.claude/skills/video-script-production/references/s2-teardown.md

# S2: the teardown of rival videos (what they do, how, and what to avoid)

**Goal.** Read the strongest rival videos on this topic closely and write down, with quotes, what they all do (table stakes you must match), what the big ones do that the small ones do not (differentiators), what their packaging promises, where they are weak (the opening a new video can take) and which of their claims you must not repeat. Output: `research/<slug>/teardown/SYNTHESIS.md`.

**Tool.** The skill `winning-video-teardown` (`.claude/skills/winning-video-teardown/`) plus two exporters from `src/topic-research/`. **It is craft analysis, not an experiment**: it cannot show that a mechanism caused a video's reach, it cannot see click-through or retention, and every interpretation is one reader's.

## 1. Do you need S2 for this topic?

| Situation | Do |
|---|---|
| The series already has a teardown of its winners (for "why X died": 20 videos, `transcripts/series-analysis/why-x-died/teardown/aggregate.md`) and this topic's rivals add nothing new | Read that aggregate (section 7 below) and do a **lite** S2 (option C) on the 2 or 3 biggest rival videos for this topic: what they claim, how they title and open, where they are weak |
| 3 or more rival videos with real reach (hundreds of thousands of views) | Do the full S2 (option A if the user has authorised subagents, else option B on the top 2 or 3) |
| Fewer than 3 usable rival videos | Do option C and say so in the hand-off |

For Moser Baer the full S2 ran on 7 videos (4 Hindi, 2 English, 1 Malayalam); only 3 had real reach (552K, 474K, 170K views) and the other four had 719 to 7.3K, so the "big versus small" comparison was 3 against 4: a lead, not a finding. Say that kind of thing in your synthesis.

## 2. Authority: who may run the analysts

Option A uses one subagent per video. **Subagents are spawned only if the user has asked for them** (CLAUDE.md). If they have not, use B or C and record `S2 option: B` (or C) in the hand-off. Do not skip S2 silently.

| Option | What | Cost | Gate |
|---|---|---|---|
| A | one Sonnet subagent per video, full JSON analysis, validator, aggregate, report, synthesis | the most; needs the user's OK | all analyses pass the validator; synthesis written with spot-checks |
| B | you act as the analyst for the 2 or 3 biggest videos, one at a time, using the same task files, JSON and validator; then synthesis | medium | each analysis passes the validator; synthesis written |
| C | lite: read the 2 or 3 biggest transcripts yourself and write `SYNTHESIS.md` from the template in section 6, quoting; no JSON, no validator | low | synthesis written; every claim in it has a quote and a timestamp from the transcript |

## 3. Pick the videos

1. Make the channel table: `node src/topic-research/export-csv.js research/<slug>` writes `all-videos.csv` (every video S1 saw, with channel subscriber counts). It visits every channel seen, which is slow for ~100 candidates. **Shortcut that worked:** copy `search.json` to `search.json.full`, trim `candidates` to the ones you care about (for example `selected` plus the next ten by views), run the export, restore the full file.
2. Choose 5 to 8 videos (3 for B or C): the most-viewed that are **about the story you will tell**; a mix of big and small channels (the contrast is the information); the original spoken languages are fine (Hindi, English, Malayalam all worked), but avoid videos with no usable captions; no more than 2 per channel; not rebirth/stock-tip/product videos. Write the reason for each in the synthesis.
3. Export them: `node src/topic-research/export-cohort.js research/<slug> research/<slug>/teardown/cohort-<slug> <videoId> <videoId> ...`. This fetches any missing transcript and writes one `.txt` per video in the layout the teardown reads. Views per day comes from YouTube's rounded age text and is approximate; likes and the description are not captured.

## 4. Prepare, analyse, validate, aggregate, report

```
# prepare: case files, thumbnails, one task file per video
node .claude/skills/winning-video-teardown/scripts/prepare.js --cohort research/<slug>/teardown/cohort-<slug> --out research/<slug>/teardown/run --perf-unknown
```

`--perf-unknown` (added 2026-10-25) tells the analyst that the video was picked for its topic, not because it outperformed. Without it, the task files say "this video performed far above the norm", which is false for a topic cohort (the Moser Baer run edited the case files by hand). Output: `run/cases/Vxx/` (`case.md`, `transcript.txt`), `run/thumbs/`, `run/tasks/analyze_Vxx.md`, `run/analyses/` (empty), `run/manifest.json`. Group labels come from the cohort folder name.

**Analyse (option A).** Spawn `general-purpose` subagents with `model: "sonnet"` (Hindi and English captions need more than Haiku), at most 20 at once, one pilot first. Every subagent gets exactly:

> Read the task file `<task path>` and follow it exactly. Read only the files it lists. Finish with one line: output path + validator result.

**Analyse (option B).** For each task file, do what it says yourself: read `analyst-prompt.md`, `taxonomy.md`, `schema.md`, the case, look at the thumbnail with the Read tool, read the **entire** transcript, write the JSON, run the validator it names, fix until it prints `OK`. Rules from the analyst prompt: mechanism not praise; every claim in `doing_well` and `script.mechanisms` carries a verbatim quote (4 to 25 words, original language, English gloss) and its timestamp; find every open loop; type every junction (THEREFORE, BUT, AND_THEN, NEW_TOPIC) with a quoted hinge; record how each hero figure was framed; name real weaknesses; do not speculate about the audience or the algorithm.

**Validate.** `node .claude/skills/winning-video-teardown/scripts/validate.js --file run/analyses/V01.json --case run/cases/V01 --strict 1`. It checks structure, that every mechanism id is in `taxonomy.md`, minimum counts (3 to 6 `doing_well`; at least 5 script mechanisms), and that **at least 85% of the quoted passages literally occur in the transcript**. A failing analysis is rewritten, not patched by loosening the validator.

**Aggregate and report (A and B).**

```
node .claude/skills/winning-video-teardown/scripts/aggregate.js --run research/<slug>/teardown/run   # aggregate.md/json: mechanism counts by group, loop stats, promise delivery, proposed new mechanisms
node .claude/skills/winning-video-teardown/scripts/report.js    --run research/<slug>/teardown/run   # teardowns.md: one section per video
```

## 5. Write the synthesis (`teardown/SYNTHESIS.md`) — the only part that is prose

Read `aggregate.md` and `teardowns.md`, and read **at least five** analyst claims against the transcripts yourself; drop or downgrade any the text does not support. Rules from the skill: report prevalence honestly ("in 3 of 7", not "always"); a mechanism present in nearly every video is **table stakes**, not an explanation of why one beat another; fold two or more independent `new_mechanisms` into `taxonomy.md`, report single ones as single observations; say what the method cannot show (causation, click-through, audience, retention). Watch for a loose category inflating counts (the first 20-video run tagged expectation reversal in 19 of 20 because the genre's peak-to-collapse turn matched it).

## 6. The synthesis template (it is the structure of the Moser Baer one)

```
# What the <topic> videos do, and how
Teardown of N YouTube explainers on <topic> (languages). One analyst per video / I read each transcript and thumbnail. Every quote was checked against the transcript (K of M passed).

## Read this first: what this can and cannot tell you
- Not all of these are winners (say which have reach). The comparison of big vs small is a vs b: a lead, not a finding.
- No causation; no click-through, retention or audience.
- Transcripts are auto-captions (names garbled; corrections made).

## Table stakes (in N of N, so they do not explain why one video beat another)
- Script: ...   - Title: ...   - Thumbnail: ...
## Common but not universal      (with counts)
## Where the big videos differ from the small ones (a vs b, a lead only)      (a table of moves)
## Moves worth copying           (each quoted, with the video and timestamp)
## Where these videos are weak   (the opening a new video can take: unexplained jargon, dropped promises, dead stretches, unverified claims)
## Claims these videos make that I could not or did not verify      (feeds "Claims you must NOT use")
## New mechanisms (single observations)
## Spot-checks I did            (which claims, what the transcript says)
## Packaging notes              (the title formulas, the thumbnail pattern, the promise vs what the video delivers)
```

The last two sections of the Moser Baer synthesis are the model: `research/the-fall-of-moser-baer/teardown/SYNTHESIS.md`.

## 7. What to carry into the script (S4 and S5)

| From the synthesis | Used in |
|---|---|
| Table stakes | the minimum you must have (a rise-and-fall arc; specific numbers; peak-versus-trough pairs; a household brand and a disaster word in the title; the logo and strong colour contrast in the thumbnail) |
| Differentiators | what to do better or differently; the contrast between big and small |
| Weak points and unexplained jargon | the opening to take; the glosses to write (Lesson A7) |
| Title formulas, thumbnail patterns, promise-versus-delivery | the packaging options and the title/evidence tension (S4) |
| Loop and promise statistics (first loop time, time to promise) | the hook's first payoff inside 30 s and the ladder (Lesson B) |
| Their unverified claims | the do-not-use table (after S3 fails to find them) |
| Where our lessons and the winners disagree | write it in `learnings.md` and tell the user |

**The genre baseline** (from the 20 "why X died" winners, `aggregate.md`, counts of videos in which an analyst found and quoted the mechanism): rise-and-fall arc 17/20; peak-versus-trough numbers 17/20; specific numbers 16/20; open loop 16/20; utility payoff 14/20; a named villain, person or decision 13/20; one stated central thesis 13/20; forward tease 10/20; analogy 9/20; named protagonist 8/20; viewer self-reference 8/20; recognisable presenter persona 6/20. Titles: a household brand 19/20; a franchise formula ("Rise and Fall of X", "Why X failed") 17/20; a disaster frame 17/20. Thumbnails: a recognisable logo 18/20; three or fewer words 17/20; strong colour contrast 15/20; a human face with strong emotion 14/20. Loops: about 4.4 per video, 92% closed, the first at about 34 s; time to the promise averages 43 s. (Expectation reversal 19/20 is inflated by the genre; ignore it.)

## 8. Gate to leave S2

- [ ] `teardown/SYNTHESIS.md` exists with the sections above; the option used (A, B or C) is stated at the top.
- [ ] Every claim in it has a quote and a timestamp; at least five were checked against the transcript by hand.
- [ ] For A and B: every analysis passed the validator (`OK`), and `aggregate.md` and `teardowns.md` exist.
- [ ] The unverified claims are listed for S3; the table stakes and weak points are listed for S4.

## 9. Pitfalls

- Treating a topic set as winners. Use `--perf-unknown` and say how many have reach.
- Counting a table-stakes mechanism as a differentiator.
- Copying a rival's dramatised or unsourced claim into the script. They go in the do-not-use table.
- Hindi or Malayalam captions: names are garbled; an analyst wrote "Rahul Puri" for Ratul Puri. Work from meaning, correct names against sources in S3, and say so.
- Analysts flatter. The prompt requires real weak points; if a teardown has none, re-run it.
- Doing S2 before S1: the cohort comes from S1's `search.json` and transcripts.

## 10. What to record

In `learnings.md`: which option, how many videos, how many had reach, how many analyses failed validation first time, the table-stakes list, and anything in the winners that contradicts a lesson.