retention_graph_analysis v1.0.0

name: retention_graph_analysis description: "Read a YouTube audience retention export, find the exact drop points, match each drop to the transcript line spoken there, separate hook leaks from cliffs and mid-video slides, and turn the read into specific edit changes. Use when someone asks why viewers stop watching, shares a retention CSV or chart, wants a retention teardown, or wants to fix pacing or a weak intro."

Retention Graph Analysis

Purpose

A retention curve on its own only shows where viewers left. Paired with the transcript, it shows what was said at the moment they left, which is what makes an edit decision possible. This skill runs that pairing every time: export in, transcript matched teardown out, with one biggest leak named first and a specific change for each finding.

It covers long-form videos first. Shorts need a shorter hook window and a duration flag, covered below.

Workflow

1. Get the export and the transcript for the same video.

• Studio path: YouTube Studio, Content, open the video, Analytics, Overview or Engagement tab, Audience retention report. Use SEE MORE for the detailed view and its download. Retention data typically takes 1 to 2 days to process, and the report exists only at video level.
• API path: YouTube Analytics API audience retention report, dimensions elapsedVideoTimeRatio, metrics audienceWatchRatio,relativeRetentionPerformance, filter for a single video ID. See references/api-and-formats.md.
• Transcript: the video's captions exported as .srt or .vtt, or a timestamped .txt. A transcript without timestamps cannot be matched to drops, so say that plainly and still run the curve-only read.

1. Run the tool. It sniffs comma, semicolon, and tab delimiters and handles decimal commas in non-comma files.

bash
   python3 bin/retention.py retention.csv --duration 600 --transcript transcript.srt
   python3 bin/retention.py retention.csv --duration 600 --json
   python3 bin/retention.py retention.csv --duration 45 --hook-seconds 5
   

• --duration is the video length in seconds. It is required when the position column is a 0 to 1 ratio or a percent, and it must match the video the export came from.
• --hook-seconds defaults to 30, the Intro window YouTube Help uses. For a Short, pass the real length and a hook window of 3 to 5 seconds.
• --cliff-points defaults to 3 points within 30 seconds. It is a triage heuristic, not a platform standard.

1. Classify every loss into one of three problems. Do not blend them, the fixes differ.

• Hook leak: points lost from the start to the end of the Intro window. Read it against the title and thumbnail promise and the first lines spoken.
• Cliff: one steep drop at one moment. Read the transcript line in the table before guessing a cause.
• Slide: the steady points-per-minute loss across the middle, from the hook end to 80 percent of the video. A slide is pacing, not one bad line.

1. Read spikes and flat stretches with both interpretations open.

• A spike means a segment was watched more than the segment before it, usually from rewatching or sharing. It can also mean the segment was unclear and viewers had to watch it again. Check the line for density before calling it a win.
• The flattest 30 seconds is a top moment candidate: a stretch where almost no one left. If it sits late, test moving that material earlier next time.

1. Compare before concluding. Typical retention in Studio compares the video to the channel's 10 latest videos of similar length, and SEE MORE compares to YouTube videos of similar length. Use those comparisons. There is no universal good retention percentage in YouTube Help, so never present one, and never present the tool's thresholds as one.
2. Segment when the answer depends on who left. Studio can split retention by new vs returning viewers, subscribers vs non-subscribers, and organic vs paid traffic. A hook leak among new viewers with subscribers holding points to a title and thumbnail match problem. The same leak in every segment points to the opening itself.
3. Write the teardown in the Output Contract order, biggest leak first, one change per finding. If the hook is tight, no cliff clears the threshold, and the slide is shallow, say the video held and the problem is likely packaging or topic, not the edit.

Output Contract

Deliver, in this order:

1. Header numbers: duration, retention at start, percent still watching at the Intro mark, hook leak in points, percent still watching at the end, middle slide in points per minute.
2. Biggest leak first: name the single largest loss, the timestamp if it is a cliff, and the transcript line spoken there, quoted from the transcript file.
3. Cliffs table: timestamp, drop size in points, line spoken. One row per cliff, worst first if the user asks for a short version.
4. Spikes list with the dual reading noted, and the flattest 30 second stretch with its line.
5. Edit changes: one specific change per finding, written as an edit instruction (cut, move, shorten, signpost, add an on-screen label), not as general advice. Name the next video check that would confirm the change worked, usually typical retention on the next similar-length video.

Worked sample output is in references/worked-teardown.md. Cause patterns for common cliff locations are in references/teardown-patterns.md.

Operating Rules

• Every factual claim about YouTube reporting must trace to YouTube Help or the YouTube Analytics API docs. Sources are listed in references/api-and-formats.md. Unverified numbers, benchmarks, and algorithm claims get cut, not softened.
• Never invent a good retention target. Label every threshold in the report as a heuristic.
• Quote transcript lines exactly from the supplied file. If no transcript was supplied, say drops are located in time only and ask for the captions file rather than reconstructing dialogue from memory.
• audienceWatchRatio can exceed 1.0 when viewers rewatch a segment, and absolute segment views can exceed the total view count for the same reason. Values above 100 percent are data, not an error. On a Short, values above 100 percent usually mean looping.
• Do not judge a video in its first hours. Retention takes 1 to 2 days to process, so early curves are incomplete.
• One video is one data point. Before recommending a channel-wide change, check whether the same cliff location or hook pattern repeats across at least three similar-length videos.
• The tool reads files only. It does not call YouTube, publish, or edit any video.