retention-doctor

---
name: retention-doctor
description: Reads a short video's retention curve and names the exact second people leave, why, and the one edit that fixes it. Use when a video underperformed and you want a diagnosis, not a guess.
---

# Find the second people leave, and fix it

A named drop-off second, a cause, and a rewritten line for it.

## Claude does

1. Ask for four things, refusing to start without the first two: **retention data** (screenshot or per-second percentages), **length in seconds**, **script with rough timings**, **platform**.
2. Classify the curve: **cliff** (steep loss inside 3 seconds), **slide** (steady bleed), **dip-and-recover** (one bad passage), **flat-with-loop** (healthy, above 100% from replays).
3. Score against published benchmarks and name the misses: **~75% through the stop-phase, ~70% through the hold-phase, above 100% for replays**; Hoyos targets **90%+ counting loops**.
4. Name the **single second with the largest percentage-point fall** and quote the script line running at it. Never estimate a second the data does not cover.
5. Diagnose that second on the five-dimension rubric: **hook strength 0.30, standalone coherence 0.25, emotional intensity 0.20, value density 0.15, payoff quality 0.10**, minimum 60. Say which dimension collapsed.
6. Apply the per-segment responsibility model: the opener must **prove the promise the first frame made**, every later stretch justifies its own existence, and a large opening drop is normal, not a cliff.
7. Rewrite that exact second: new spoken line, new on-screen text, and a new opening visual if the drop is inside the first 3 seconds.
8. Refuse to guess: no invented percentages, no assumed platform, no thumbnail-only diagnosis.

## Then Codex does

Codex takes the bulk arithmetic: a long export parsed into per-second deltas, every 3-second segment scored on the five weighted dimensions, the weak ones ranked. Repetitive computation over many rows, not judgement, so Claude keeps the diagnosis and the rewrite.

Claude fills `{RETENTION_DATA}`, `{TRANSCRIPT_TIMED}`, `{VIDEO_LENGTH}` and `{PLATFORM}` into `CODEX.md`, then runs:

```
codex exec --sandbox danger-full-access --skip-git-repo-check -C "<working folder>" - < CODEX.md
```

## Claude checks

1. The named worst second sits inside the supplied data range, or reject and rerun.
2. Every percentage traces to a supplied row. A figure appearing nowhere in the input is invented: reject.
3. Recompute one weighted total by hand. Wrong arithmetic, reject and rerun.
4. Check what a low score is **for**. A quiet beat before a payoff scores low on emotional intensity by design: a working device, not a fault.
5. If every segment clears 60 while the video underperformed, suspect the instrument rather than invent a fault. Two failed runs and Claude scores it itself.

## Rules

- A number off a screenshot is a lead; a number in an export is a finding. Say which.
- Diagnose from the curve, never the script alone.
- "The algorithm" is not a cause. Name the second.
- Public information only.
- Never invent a fact, a number or a quote.
- Anything sent in someone's name says whose name it is.

## If Codex is not installed

Claude parses and scores it directly, and says so.

## Built from

- AgriciDaniel/claude-youtube, https://github.com/AgriciDaniel/claude-youtube - 350 stars (api.github.com, 5 Sep 2026); curve-shape classification.
- AgriciDaniel/claude-shorts, https://github.com/AgriciDaniel/claude-shorts - 204 stars (same source and date); the weighted rubric.
- social-media-skills/skills, https://github.com/social-media-skills/skills - 66 stars (same); phase benchmarks.
- Jenny Hoyos and Todd Sherman, https://blog.youtube/creator-and-artist-stories/youtube-shorts-deep-dive/ - published by YouTube; the 90%-with-loops target.
- MrBeast production handbook, https://simonwillison.net/2024/Sep/15/how-to-succeed-in-mrbeast-production/ - per-segment responsibility model.

# Find the second people leave - Codex task

## You are given

- `{RETENTION_DATA}` - retention figures for one short video. Either a list of `second, percentage` pairs, or a pasted analytics export. It may be messy, out of order, or contain duplicate seconds.
- `{TRANSCRIPT_TIMED}` - the script or transcript, one line per entry, each with a start second.
- `{VIDEO_LENGTH}` - total video length in seconds.
- `{PLATFORM}` - one of YouTube Shorts, TikTok, Instagram Reels.

## Produce

1. **A per-second delta table.** Columns: second, retention percentage, change from the previous second in percentage points. One row per second present in the data, sorted ascending. Do not interpolate seconds that are missing; mark them `no data`.
2. **The three largest single-second falls**, ranked, each with the second, the fall in percentage points, and the transcript line running at that second (or `no line` if the transcript has no entry covering it).
3. **A segment score table.** Split the video into 3-second segments from 0 to `{VIDEO_LENGTH}`. Score each segment 0-100 on five dimensions and produce a weighted total:
   - hook strength, weight 0.30
   - standalone coherence, weight 0.25
   - emotional intensity, weight 0.20
   - value density, weight 0.15
   - payoff quality, weight 0.10
   Show the five raw scores, the weighted total to one decimal place, and `KEEP` if the total is 60 or above, `WEAK` if below.
4. **Threshold check.** State the retention at the final second, whether it exceeds 100% (replays), and whether the curve stays above 70% through the first third and above 60% overall. Print each as `pass`, `fail` or `no data`.

Output plain Markdown tables. No prose commentary, no recommendations, no rewrite suggestions.

## Rules

- Every percentage you print must appear in `{RETENTION_DATA}` or be a difference computed from two figures that do. Never estimate a missing value.
- If `{RETENTION_DATA}` cannot be parsed into second-and-percentage pairs, print `UNPARSEABLE` and the first five lines you could not read, then stop.
- If a second in your output does not exist in the input, that is a defect: drop the row.
- Show your arithmetic for the weighted total on the lowest-scoring segment so it can be rechecked by hand.
- Do not fetch anything from the internet. Work only from the text given.
- Do not write files outside the working folder.

## Return

Print, in this order:
1. `ROWS PARSED: <n>` and `RANGE: <first second> to <last second>`.
2. The per-second delta table.
3. The three largest falls table.
4. The segment score table.
5. The threshold check block.
6. `WORST SECOND: <n> (<fall> pp)` on its own final line.