.claude/skills/within-channel-study/SKILL.md

---
name: within-channel-study
description: Work out what makes some videos on ONE YouTube channel win and others fail, by reading the titles and transcripts of its best, median and worst videos against the rest of its catalogue. Output is a set of practical, evidence-backed observations a creator can use (for example "naming a disaster in the title pulls clicks", "revealing the hidden workings of an everyday thing wins"). No raters, no scores. Checks first that the catalogue is mined and the six sample transcripts exist. Use when the user names a channel and wants to know what separates its hits from its misses.
---

# Within-channel study

## What this is

Videos on one channel share the same audience, thumbnail style, authority and baseline. Comparing its best, median and worst
videos therefore holds most channel-level causes constant, and what remains to differ is the video itself:

| Layer | What varies | Where we can see it |
|---|---|---|
| **Topic / idea** | the subject, and how much demand it has | title, nearest catalogue neighbours |
| **Promise (packaging)** | what the title makes the viewer expect, how it is worded | title |
| **Script** | whether and when the promise is delivered, structure, specificity, pace, ending | transcript |
| **Format / length / series** | duration, "Part N", animation vs talking head | metadata, title |
| **Timing and luck** | news peg, algorithm push, age | publish date, age flags |
| **Thumbnail** | NOT observed; assumed similar across the channel | |

The deliverable is a list of **practical observations**: short statements a creator could act on, each backed by evidence
from the sampled videos and checked against the whole catalogue. Six videos give leads, not proof, so every observation
carries an honest strength label and the evidence against it.

No scoring and no rating. Every claim ties to a quote, a title or a number.

`S` below means `node ".claude/skills/within-channel-study/scripts/...`, run from the project root.

## Step 0: prerequisites gate (always first)

```
node S/check-prereqs.js --channel "<name | @handle | url>" [--db data/<ecosystem>.db]
```

It verifies that (1) the catalogue is mined (`npm run catalogue:mine`: at least 10 rankable videos, at least 50% coverage) and
(2) the transcript sample exists (`npm run transcripts:sample`: `_index.json` plus `best-1, best-2, median-1, median-2, worst-1, worst-2`).

| Exit | Meaning | What to do |
|---|---|---|
| 0 | ready | go to step 1 |
| 2 | catalogue not mined | give the user the printed command (mines, then samples) |
| 3 | transcripts missing/incomplete | give the user the printed `--skip-mine` command |
| 4 | channel unknown to every database | ask for the full channel URL and give the sampler command |
| 5 | channel too small (under 10 rankable videos) | stop; re-mining cannot help |

**Do not run the sampler yourself unless the user says to.** It is slow and uses the network. Print the command, say which
prerequisite failed, stop, and re-run the gate after the user has run it.

## Step 1: build the dossier

```
node S/dossier.js --channel "<name>"
```

Writes two files in `transcripts/<channel>/_study/`:
- `dossier.md`: channel baseline, the six videos with confound flags, title facts, **nearest catalogue neighbours** per title
  (same topic words elsewhere on the channel), and per transcript the opening 90 s, a ten-slice skeleton and the ending.
- `catalogue-titles.md`: every rankable title, best to worst by views/day, tagged TOP (top 20%), MID, LOW (bottom 20%), with
  the six sampled videos marked. This is the evidence base for step 5.

Read both fully before forming a view.

## Step 2: comparability check (write this down first)

In 3-6 lines: how large the best-to-worst spread is; which of the six are unfair comparisons (young videos, approximate dates,
unusual length, "Part N", fallback pool); and whether best and worst share a format. If the worst videos are a different
format, say that the contrast is format and avoid script conclusions from it.

## Step 3: notice (read titles first, then transcripts)

Read the six titles side by side, then the neighbours, then the transcripts. You are looking for **what the winners do that the
losers do not, and the reverse**, in terms a creator would recognize. The lists below are prompts for noticing, not a checklist;
also record patterns that fit none of them.

**Title and packaging levers to look for**
- Authority or insider voice: words that claim knowledge or candour ("actually", "really", "the truth", "exposed", "the math"),
  a confident verdict rather than a topic label.
- Reveal of a familiar real-world thing: the viewer already uses, sees or pays for it (a bus, rent, a petrol pump) and is
  promised its hidden workings or economics.
- Loss, disaster or decline: crash, dying, collapse, fooling everyone; whose loss it is (the viewer's, or other people's).
- Personal stake: the viewer's own money, home, job or safety, versus other people's drama.
- Specific number, magnitude or comparison (₹ figures, "vs", "in 17 minutes").
- Named person, brand or controversy, and whether the name carries pull on its own.
- Curiosity gap versus plain description; verdict-first versus question-first.
- Template reuse: the same title frame on different subjects (the neighbours show whether the frame or the subject earns the views).
- Format tags and series markers, title length, language or script of the title.

**Transcript levers to look for**
- First 90 s: scene placing the viewer in a familiar situation, a number, a claim, a question, or context-setting. Seconds until
  the viewer learns what the video is about.
- Promise delivery: where the payoff the title promised appears (early, late, never), and whether the opening matches the title.
- Specificity and novelty: concrete figures, names, mechanisms versus recycled general knowledge.
- Structure from the skeleton: stacked reveals, a single build, a list; pacing and padding (words per minute, repetition).
- Direct address and viewer stake: "you" with the viewer's situation versus narration about others.
- Ending: closes the loop and gives a takeaway, or stops.

## Step 4: write the observations (the core output)

Write **6 to 10** observations. Each one is a practical statement in plain language, phrased as something that works or does not,
in this exact shape:

```
O3. Naming a disaster in the title ("X is dying", "how Y crashed") pulls clicks, but only when it is about something the viewer relies on.
  Practical takeaway: <one sentence a creator can apply>
  Evidence for:
    - <title> (<views/day>, rank r/n, <x>x median) ...
    - <transcript quote> [video id mm:ss] ...
  Evidence against / where it fails:
    - <counter-example with numbers>, or "none found in the ledger"
  Catalogue count (from catalogue-titles.md): e.g. "7 of the 10 TOP titles name a loss; 1 of the 10 LOW titles"
  Layer: promise | topic | script | format | timing
  Strength: strong | moderate | tentative   (why)
  Alternative explanation: <age, length, series, news peg, topic demand ...>
```

Requirements:
- Phrase it as a lever, not a description. "A sprinkle of authority words makes people click" is an observation; "the best video is
  about buses" is not.
- Every observation needs at least two pieces of evidence for and an honest line for against. If you cannot find a counter-example,
  say you looked and found none.
- Include observations about what **fails** (disaster aversion applied to other people's affairs, generic topic labels, abstract
  titles), not only what wins.
- Include at least one observation about the middle videos: what holds them at the median (usually a weaker promise or a subject
  with lukewarm demand), so the gradient from best to worst is explained, not just the extremes.
- Do not write an observation the six videos do not support at all. Do not pad to reach the count.
- Strength rules: **strong** = appears in most best and few worst, holds in the catalogue counts, counter-examples have a clear
  other explanation. **moderate** = holds in the sample or the catalogue counts but not both cleanly. **tentative** = reading only.

## Step 5: check each observation against the catalogue by reading (no statistics)

Using `catalogue-titles.md`, for each observation count how many TOP-tier and LOW-tier titles show the pattern, and list the
notable exceptions with their numbers. Look at the neighbours too: a title frame that wins on one subject and flops on another
means the subject, not the frame, is doing the work, and the observation must say so. Update the strength label from what you find
and drop or reword any observation the ledger contradicts. Keep the contradicted ones in the report, marked as contradicted.

**Do not run `probe.js` unless the user explicitly asks for it.** When asked:
`node S/probe.js --channel "<name>" [--token "a,b"] [--regex "name=pattern"]`. It reports median views/day with and without each
title feature plus a permutation p-value, and a recency check. It is a screening tool: about one feature in twenty passes p<0.05 by chance.

## Step 6: write `transcripts/<channel>/_study/report.md`

1. **Headline**: 3 to 5 sentences. What separates this channel's hits from its misses, in plain language.
2. **Observations**: the step 4 blocks, ordered strongest first, updated by step 5.
3. **Comparability and flags**: the step 2 notes.
4. **The six, one short paragraph each**: promise, delivery, result against the channel median.
5. **Unexplained**: videos or gaps no observation covers. Do not force a story.
6. **Check outside this data**: thumbnails, first-day distribution, comments, news events or collaborations for the best and worst.
7. **Limits**: n, flags, estimated dates, thumbnail not observed, views/day is age-floored.

## Rules

- Tag every claim by evidence type: **observed** (a quote or number), **counted** (from the ledger, with the counts), **lead** (reading only).
  Never describe a lead as a finding.
- A trait shared by the best and the worst is not an explanation.
- The six videos inspire an observation; the ledger, the neighbours or other channels test it. Never confirm an observation with the
  same videos that suggested it.
- An idea carried over from another channel is a candidate to look for here, never a result.
- Quote briefly and in the original language, with an English gloss in brackets when the transcript is not English.
- If the gate fails or the channel is too small, say so plainly; do not write a report from an incomplete sample.