luckiest-co 1.0.53 → 1.0.55

package/skills/youtube-planner/SKILL.md

@@ -20,10 +20,10 @@ description: >-
 argument-hint: "[topic or video idea] [--channel <url>] [--readout <video-url>]"
 user-invocable: true
 license: MIT. See ATTRIBUTION.md
-compatibility: Python 3.10+ and yt-dlp for the floor and ceiling check. Works without them, with the user's own numbers.
+compatibility: Python 3.10+ for the scripts, and yt-dlp for the floor, ceiling, and channel outlier checks. Works without them, with the user's own numbers.
 allowed-tools: Bash, Read, Write, Glob, Grep, AskUserQuestion
 metadata:
-  version: "1.1.0"
+  version: "1.2.0"
   listing_id: luckiest-youtube-planner
   author: luckiest
 ---
@@ -44,11 +44,11 @@ first run of a session.
 ## Staying current
 
 On activation, call the Luckiest MCP `check_updates` tool with
-`{ listingId: "luckiest-youtube-planner", installedSemver: "1.1.0" }`. If
+`{ listingId: "luckiest-youtube-planner", installedSemver: "1.2.0" }`. If
 `upToDate: false`, surface the `notice` once and continue. Never block on it.
 
 When done, call `report_usage` once with
-`{ listing_id: "luckiest-youtube-planner", skill_version: "1.1.0", matched: true, success: <true|false> }`.
+`{ listing_id: "luckiest-youtube-planner", skill_version: "1.2.0", matched: true, success: <true|false> }`.
 Metadata only, never prompt text. Skip silently if unavailable.
 
 ## Standing rules
@@ -77,6 +77,10 @@ already said or `youtube-plan.md` already holds:
    sales, build authority, or test a format.
 3. Do you have a channel URL? It is optional and only used for your own median views.
 
+If `voice.md` exists in the working directory or `~/.claude/youtube/`, read it
+before writing any spoken line: the hook has to sound like the person saying it.
+Do not create one unless asked.
+
 If the user brought a published video and asked why it flopped or how it is
 doing, jump to Step 6 with `--readout`.
 
@@ -99,27 +103,51 @@ Pick topics the audience already chooses to watch, not topics they say they need
 3. Drop a topic when its floor is not worth the effort for the goal, when most
    views are older than 12 months (stale demand), or when the counts look
    bought (huge views, almost no comments).
-4. Raise the ceiling: try bundling the topic with a bigger draw (a known name,
+4. With a channel URL, or two or three channels the audience already watches,
+   find what beat its own channel:
+
+   ```bash
+   python3 "${SKILL_DIR}/scripts/floor_ceiling.py" --channel '<url>' --channel '<url>' --limit 30
+   ```
+
+   It ranks videos by their multiple over their own channel's median and skips
+   channels with fewer than 4 counted videos. A 5x video on a small channel says
+   more about the idea than an ordinary video on a big one.
+5. Raise the ceiling: try bundling the topic with a bigger draw (a known name,
    a broader problem, a time hook) and rerun the script on the bundled phrase.
    Keep the bundle only if the floor holds and the video can still deliver it.
-5. Score the chosen idea 1 to 10 with the rubric in stages.md.
+6. Score the chosen idea 1 to 10 with the rubric in stages.md.
 
 ## Step 3: Packaging (stage 2)
 
 The video sits beside about 20 others in home or search. It has to be noticed,
 then understood, then clicked, before the eye moves on.
 
-1. Write 5 title options using framings that win across niches. Name the
+1. Write 10 title options using framings that win across niches. Name the
    pattern and the reason it works for this audience on each.
-2. Pick the best 2 and pair each with a one-line thumbnail concept: what stands
-   out at phone size, and what the viewer understands at a glance. The title
-   and the thumbnail must say different things. The thumbnail opens the
-   question, and the title closes it just enough to earn the click.
-3. Lint each pairing: under 60 characters so it does not truncate, no word the
-   thumbnail already shows, and a promise the body will keep.
-4. Gut check: is the user a little nervous about messing this up? If the idea
+2. Pair the strongest with thumbnail text (3 words at most) and a one-line
+   thumbnail concept: what stands out at phone size, and what the viewer
+   understands at a glance. The title and the thumbnail must say different
+   things. The thumbnail opens the question, and the title closes it just
+   enough to earn the click.
+3. Lint the pairings, one `title | thumb` per line in a file:
+
+   ```bash
+   python3 "${SKILL_DIR}/scripts/pairing.py" pairings.txt
+   ```
+
+   It flags the desktop cut (60 characters), the mobile cut (40), a thumbnail
+   that repeats a title word, more than 3 thumbnail words, more than 2 all-caps
+   words, vague adjectives, no number, name, or date, and filler up front. Show
+   the top 3 with their scores and issues, then keep 2. The lint cannot check
+   the promise: confirm by hand that the body will keep it.
+4. Query test: write the 3 searches a real viewer would type to find this video.
+   The title and the first 2 lines of the description must contain the words of
+   those searches. If they do not, fix the title, not the description. Tags
+   barely matter: keep them to spellings and names people actually type.
+5. Gut check: is the user a little nervous about messing this up? If the idea
    feels safe, it is usually too small. Say so.
-5. Score it. For thumbnail images, hand off to **luckiest-image** with the
+6. Score it. For thumbnail images, hand off to **luckiest-image** with the
    chosen concept.
 
 ## Step 4: Hook (stage 3)
@@ -133,8 +161,20 @@ the doubt by answering four questions, in any order:
 - **Persona**: is this for me? Name who it is for, and who it is not for when the
   packaging could attract the wrong viewer.
 
-Write the hook as spoken lines and score it. A hook that only teases, with no
-promise and no plan, fails this stage.
+Rules for the opening lines:
+
+- The first sentence confirms the title. A hook that ignores its own title is
+  why viewers leave in the first 10 seconds.
+- One promise. A hook that carries two keeps neither.
+- Specific beats big: a number, a name, or a date, never "massive".
+- If the title promises a thing (a template, a result, a tool), show it within
+  20 seconds.
+- No channel intro, no "who I am", and no subscribe ask before 0:45. These are
+  the usual cause of the drop at 0:30.
+
+Write 3 versions as spoken lines, score each, and show the user the best 2.
+Never hand over just one. A hook that only teases, with no promise and no plan,
+fails this stage.
 
 ## Step 5: Body (stage 4)
 
@@ -155,9 +195,20 @@ Build the outline from the title's promise, not from everything the user knows.
    - **Reopen**: as soon as one question closes, open the next one.
    A good video has one loop. A great one has a new loop starting before the
    last one ends. Mark each loop's four beats on the outline.
-5. The video is done when every item is delivered, not when it looks done. Aim
+5. Mark every beat with what is on screen, as `[ON SCREEN: ...]`. A talking head
+   with nothing to look at is a podcast.
+6. Name each section in 5 words or fewer. A section that cannot be named that
+   briefly is two sections or filler. The names become the chapters: the first
+   at 00:00, at least 3 of them, each at least 10 seconds long, or YouTube does
+   not show them.
+7. Estimate the runtime at 150 spoken words per minute.
+8. Mark 3 Short candidates on the outline: 20 to 55 seconds that open on a
+   complete thought, contain a turn, and end on a line, not a trail-off. Write
+   a new first line for each, since the original assumes context the Shorts
+   viewer lacks. Hand them to **luckiest-social** after the video ships.
+9. The video is done when every item is delivered, not when it looks done. Aim
    to beat the expectation. Satisfaction is the goal, and retention follows it.
-6. Score it. For the spoken script, hand off to **luckiest-video-studio-script**
+10. Score it. For the spoken script, hand off to **luckiest-video-studio-script**
    with the hook and the outline.
 
 ## Step 6: Readout plan (stage 5)
@@ -171,10 +222,25 @@ Write down, before publishing, how the user will judge the result:
 - Metrics point to where to look, never to the fix. Low CTR means look at the
   pairing and ask why. A sharp retention drop means look at that exact moment.
 
-With `--readout <video-url>`, use **luckiest-video-watcher** in quick mode on the
-moments the user flags, and read the public comment count and like count from
-`yt-dlp --dump-json`. Report what each signal says, which stage it points to,
-and the one change to test next.
+With `--readout <video-url>`:
+
+1. Read the public comment count and like count from `yt-dlp --dump-json`.
+2. If the user exports the retention chart from Studio, read it:
+
+   ```bash
+   python3 "${SKILL_DIR}/scripts/retention.py" retention.csv --duration <seconds> --transcript <file.srt>
+   ```
+
+   It reports the hook leak (first 30 seconds: under 25 points healthy, under 40
+   leaking, else severe), the steepest cliffs with the words spoken there, and
+   the slide across the middle. Use **luckiest-video-watcher** in quick mode on
+   the cliff moments.
+3. Sort the comments the user pastes into four piles and count each: questions
+   (next video topics, note the repeats), corrections (concede the right ones),
+   praise, and bait (ignore). Suggest pinning the question most viewers share.
+4. Report what each signal says and which stage it points to. End with the ONE
+   change to test next, 3 specific things that already work so they are kept,
+   and what not to change yet. Never a list of twenty fixes.
 
 ## Step 7: Gate and write
 

package/skills/youtube-planner/references/plan-template.md

@@ -26,7 +26,8 @@ Dropped: <topic>: <reason>
 ## 2. Packaging
 | Title | Pattern | Why it works here | Thumbnail |
 |---|---|---|---|
-Pick: <title + thumbnail>
+Pick: <title + thumbnail> · pairing.py <n>/100
+Queries: <query 1> · <query 2> · <query 3> (all words in the title or first 2 description lines: yes/no)
 
 ## 3. Hook
 - Promise:
@@ -37,10 +38,12 @@ Pick: <title + thumbnail>
 
 ## 4. Body
 Must be true for the title to be true:
-1. <item>
-   - <sub-item>
-First value lands at: <m:ss>
+1. <section name, 5 words or fewer>
+   - <sub-item> [ON SCREEN: <what the viewer sees>]
+First value lands at: <m:ss> · Runtime: <m:ss> at 150 wpm
 Beats expectation by: <item>
+Chapters: 00:00 <name> · <m:ss> <name> · <m:ss> <name>
+Shorts: <m:ss-m:ss> "<new first line>" (x3)
 
 ## 5. Readout
 Review on: <date>
@@ -50,7 +53,8 @@ Review on: <date>
 | Likes per view | | Body |
 | Subs per view | | Persona |
 | CTR | | Packaging |
-| Retention drops | | Hook / that moment |
+| Hook leak (first 30s) | under 25 points | Hook |
+| Retention cliffs | none over a few points | That moment in the body |
 
 ## Next
 <weakest stage>: <one action>

package/skills/youtube-planner/references/stages.md

@@ -31,16 +31,18 @@ Real views check: a video with very high views but almost no comments or likes,
 or a channel whose other videos get a tiny fraction of that, is a sign of
 bought or bot views. Leave it out of the floor.
 
-Own-channel outliers: when the user gave a channel, compare each candidate's
-top videos with their channel's own median. A video at 5x its channel's median
-says more than a big channel's ordinary video.
+Own-channel outliers: `floor_ceiling.py --channel` divides each video's views
+by its own channel's median. A video at 5x its channel's median says more than
+a big channel's ordinary video. Channels with fewer than 4 counted videos are
+skipped, since a median of two or three is noise. The pattern the outliers
+share is the signal, not any single one.
 
 ## 2. Packaging
 
 | Score | Means |
 |---|---|
-| 9-10 | A cross-niche pattern with a stated reason, a thumbnail readable at phone size, title and thumbnail that do not repeat each other, a promise the outline keeps |
-| 7-8 | All of the above, with a weaker reason or a busier thumbnail |
+| 9-10 | A cross-niche pattern with a stated reason, a thumbnail readable at phone size, title and thumbnail that do not repeat each other, a promise the outline keeps, `pairing.py` at 85 or more, and all 3 queries pass the query test |
+| 7-8 | All of the above, with a weaker reason, a busier thumbnail, or `pairing.py` at 70 to 84 |
 | 4-6 | Copies one outlier, or the title and thumbnail say the same thing |
 | 1-3 | Clickbait the body cannot pay off |
 
@@ -65,9 +67,9 @@ Thumbnail jobs:
 
 | Score | Means |
 |---|---|
-| 9-10 | All four Ps answered in under 30 seconds, proof is specific and true, plan names every step |
+| 9-10 | All four Ps answered in under 30 seconds, proof is specific and true, plan names every step, the first sentence confirms the title, and nothing about the channel comes before the promise |
 | 7-8 | All four Ps, with vague proof or plan |
-| 4-6 | Missing one P |
+| 4-6 | Missing one P, or it opens with an intro, a "who I am", or a subscribe ask |
 | 1-3 | A tease with no promise or plan |
 
 Persona matters most when the packaging could pull in two audiences. Say
@@ -77,8 +79,8 @@ plainly who it is for, so the wrong viewers leave early and the right ones stay.
 
 | Score | Means |
 |---|---|
-| 9-10 | Every outline item traces to the title's promise, first value in the first minute, nothing unrelated, at least one item that beats the expectation, and each section runs a full story loop that reopens before it closes |
-| 7-8 | Every item traces to the promise, value arrives late |
+| 9-10 | Every outline item traces to the title's promise, first value in the first minute, nothing unrelated, at least one item that beats the expectation, each section runs a full story loop that reopens before it closes, every beat has an `[ON SCREEN]` note, and every section has a name of 5 words or fewer |
+| 7-8 | Every item traces to the promise, value arrives late, or some beats have nothing on screen |
 | 4-6 | Some sections serve the creator, not the promise |
 | 1-3 | An info dump of everything the creator knows |
 
@@ -111,9 +113,16 @@ subscribe, and buy, and YouTube shows the video to more people like them.
 Signal to stage map:
 - Low CTR: inspect packaging (stage 2). Low CTR alone is not proof. Hits have
   run at 2 to 3%.
-- Early retention drop (first 30 seconds): inspect the hook (stage 3).
+- Early retention drop (first 30 seconds): inspect the hook (stage 3). From
+  `retention.py`, a hook leak under 25 points is healthy, under 40 is leaking,
+  and 40 or more is severe. Fix the first lines of the script, not the edit.
 - A cliff later: inspect that moment in the body (stage 4), for example a hard
-  call to action. Trim it after publishing if needed.
+  call to action, a sponsor read, or a topic change with no signpost. Trim it
+  after publishing if needed.
+- A steady slide across the middle: pacing. Fix it by cutting, not rewriting.
+- Hook leak healthy and the slide flat, but views low: the video is fine, so
+  inspect packaging (stage 2).
+- Comments full of the same question: that question is the next video's idea.
 - Views flat but comments glowing: inspect the idea (stage 1). The ceiling may be low.
 - Many negative or "this isn't what the title said" comments: the promise and
   the body do not match (stages 2 and 4).

package/skills/youtube-planner/scripts/floor_ceiling.py

@@ -3,10 +3,15 @@
 
 Usage:
   floor_ceiling.py '<topic>' [--limit 30] [--json]
+  floor_ceiling.py --channel <url> [--channel <url> ...] [--limit 30] [--min 2.0] [--json]
   floor_ceiling.py --self-test
 
 Floor = median views. Ceiling = p90 and max views. Fresh = share uploaded in the
 last 12 months. Entries with no view count or date are counted, never guessed.
+
+--channel ranks each channel's recent uploads by their multiple over that
+channel's own median, so a small channel's hit counts as much as a big one's.
+Channels with under 4 videos that have view counts are skipped, not ranked.
 Stdlib only. Calls yt-dlp as an external tool, with no shell.
 """
 import argparse
@@ -19,6 +24,7 @@ import subprocess
 import sys
 
 FRESH_DAYS = 365
+MIN_VIDEOS = 4
 
 
 def percentile(sorted_vals, p):
@@ -70,6 +76,52 @@ def search(topic, limit):
     return entries
 
 
+def channel_videos(url, limit):
+    if not shutil.which("yt-dlp"):
+        sys.exit("yt-dlp not found. Install it, or ask the user for view counts.")
+    url = url.rstrip("/")
+    if not url.endswith("/videos"):
+        url += "/videos"
+    cmd = ["yt-dlp", "--flat-playlist", "-J", "--no-warnings", "--ignore-errors",
+           "--playlist-end", str(limit), url]
+    out = subprocess.run(cmd, capture_output=True, text=True, timeout=300).stdout
+    try:
+        d = json.loads(out)
+    except json.JSONDecodeError:
+        return url, []
+    name = d.get("channel") or d.get("uploader") or d.get("title") or url
+    return name, [{k: e.get(k) for k in ("view_count", "title", "url")} for e in d.get("entries") or []]
+
+
+def outliers(channels, min_multiple):
+    """channels: {name: [entries]}. Returns (rows sorted by multiple, skipped)."""
+    rows, skipped = [], []
+    for name, entries in channels.items():
+        counted = [e for e in entries if isinstance(e.get("view_count"), int)]
+        if len(counted) < MIN_VIDEOS:
+            skipped.append({"channel": name, "videos": len(counted)})
+            continue
+        med = statistics.median(e["view_count"] for e in counted)
+        for e in counted:
+            m = e["view_count"] / med if med else 0
+            if m >= min_multiple:
+                rows.append({"channel": name, "median": int(med), "views": e["view_count"],
+                             "multiple": round(m, 2), "title": e.get("title"), "url": e.get("url")})
+    rows.sort(key=lambda r: -r["multiple"])
+    return rows, skipped
+
+
+def report_outliers(rows, skipped, min_multiple):
+    print(f"Outliers at {min_multiple}x their own channel median or more:")
+    for r in rows[:25]:
+        print(f"  {r['multiple']:>6.2f}x  {r['views']:>12,} vs median {r['median']:>10,}  "
+              f"{(r['channel'] or '')[:20]:<20}  {(r['title'] or '')[:60]}")
+    if not rows:
+        print("  none. Lower --min or raise --limit.")
+    for s in skipped:
+        print(f"Skipped {s['channel']}: {s['videos']} videos with views, need {MIN_VIDEOS} for a median.")
+
+
 def fmt(n):
     return "unknown" if n is None else f"{n:,}"
 
@@ -106,21 +158,39 @@ def self_test():
     assert s["top"][0]["views"] == 300000
     empty = summarize([], today)
     assert empty["floor_median"] is None and empty["fresh_share"] is None
+    chans = {
+        "small": [{"view_count": v, "title": f"s{v}"} for v in (1000, 1200, 800, 9000)],
+        "big": [{"view_count": v, "title": f"b{v}"} for v in (500000, 400000, 600000, 700000)],
+        "thin": [{"view_count": 50, "title": "t"}, {"view_count": None, "title": "u"}],
+    }
+    rows, skipped = outliers(chans, 2.0)
+    assert [r["title"] for r in rows] == ["s9000"], rows  # 9000 / median 1100 = 8.18x
+    assert rows[0]["multiple"] == 8.18 and rows[0]["median"] == 1100
+    assert skipped == [{"channel": "thin", "videos": 1}], skipped
     print("self-test ok")
 
 
 def main():
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("topic", nargs="?")
+    ap.add_argument("--channel", action="append", default=[])
+    ap.add_argument("--min", type=float, default=2.0)
     ap.add_argument("--limit", type=int, default=30)
     ap.add_argument("--json", action="store_true")
     ap.add_argument("--self-test", action="store_true")
     a = ap.parse_args()
     if a.self_test:
         return self_test()
+    a.limit = max(1, min(a.limit, 100))
+    if a.channel:
+        rows, skipped = outliers(dict(channel_videos(u, a.limit) for u in a.channel), a.min)
+        if a.json:
+            print(json.dumps({"outliers": rows, "skipped": skipped}, indent=2))
+        else:
+            report_outliers(rows, skipped, a.min)
+        return
     if not a.topic:
         ap.error("topic is required")
-    a.limit = max(1, min(a.limit, 100))
     s = summarize(search(a.topic, a.limit), dt.date.today())
     if a.json:
         print(json.dumps({"topic": a.topic, **s}, indent=2))

package/skills/youtube-planner/scripts/pairing.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""Lint a YouTube title and thumbnail text as one pairing.
+
+Usage:
+  pairing.py --title '<title>' [--thumb '<thumbnail words>'] [--json]
+  pairing.py <file> [--json]       one 'title | thumb' per line, ranked
+  pairing.py --self-test
+
+Checks: desktop search cuts near 60 characters, a mobile feed near 40, and the
+hard limit is 100. The thumbnail must not repeat a title word and should carry
+3 words or fewer. More than 2 all-caps words reads as spam. Vague adjectives
+lose to a number, a name, or a date. The first 3 words must carry the subject.
+Score is 0-100: a heuristic for comparing options, not a CTR prediction.
+"""
+import argparse
+import json
+import re
+
+DESKTOP, MOBILE, HARD = 60, 40, 100
+VAGUE = {"amazing", "awesome", "best", "complete", "crazy", "epic", "everything",
+         "huge", "incredible", "insane", "massive", "perfect", "powerful",
+         "revolutionary", "secret", "ultimate", "unbelievable"}
+FILLER = {"a", "an", "and", "are", "for", "how", "i", "in", "is", "it", "my", "of",
+          "on", "or", "that", "the", "this", "to", "what", "why", "with", "you", "your"}
+
+
+def words(text):
+    return re.findall(r"[a-z0-9']+", text.lower())
+
+
+def has_specific(title):
+    # a digit, or a capitalised word after the first (a name, a product, a month)
+    return bool(re.search(r"\d", title)) or any(w[:1].isupper() and not w.isupper()
+                                                for w in title.split()[1:])
+
+
+def lint(title, thumb=None):
+    t = title.strip()
+    n = len(t)
+    issues = []
+    if n > HARD:
+        issues.append(("length", f"{n} chars, over YouTube's {HARD} limit"))
+    elif n > DESKTOP:
+        issues.append(("length", f"{n} chars, desktop search cuts near {DESKTOP}"))
+    if n > MOBILE:
+        shown = t[:MOBILE].rsplit(" ", 1)[0]
+        issues.append(("mobile", f'mobile feed shows about "{shown}...": does the subject survive?'))
+    caps = [w for w in t.split() if len(w) > 2 and w.isupper()]
+    if len(caps) > 2:
+        issues.append(("caps", f"{len(caps)} all-caps words, keep it to 2"))
+    vague = sorted({w for w in words(t) if w in VAGUE})
+    if vague:
+        issues.append(("vague", f"{', '.join(vague)}: swap for a number, a name, or a date"))
+    if not has_specific(t):
+        issues.append(("specific", "no number, name, or date"))
+    if words(t) and all(w in FILLER for w in words(t)[:3]):
+        issues.append(("front", "first 3 words are filler, move the subject forward"))
+    if thumb:
+        shared = sorted((set(words(t)) - FILLER) & (set(words(thumb)) - FILLER))
+        if shared:
+            issues.append(("repeat", f"thumbnail repeats {', '.join(shared)}: say what the title does not"))
+        if len(words(thumb)) > 3:
+            issues.append(("thumb", f"{len(words(thumb))} thumbnail words, 3 is the most that reads at feed size"))
+    # ponytail: flat 15 points per issue, weight by kind if scores start tying
+    return {"title": t, "thumb": thumb, "chars": n,
+            "score": max(0, 100 - 15 * len(issues)), "issues": issues}
+
+
+def show(r):
+    pair = f'"{r["title"]}"' + (f'  +  [{r["thumb"]}]' if r["thumb"] else "")
+    print(f"{r['score']:>3}/100  {pair}  ({r['chars']} chars)")
+    for kind, msg in r["issues"]:
+        print(f"         x {kind:<9} {msg}")
+
+
+def self_test():
+    long = lint("This is a really long title that goes on and on past sixty characters")
+    assert any(k == "length" for k, _ in long["issues"]), long
+    rep = lint("I Tried 7 Cold Email Tools for 30 Days", "COLD EMAIL WINNER")
+    assert any(k == "repeat" for k, _ in rep["issues"]), rep
+    clean = lint("I Tried 7 Cold Email Tools for 30 Days", "ONE WON")
+    assert clean["issues"] == [] and clean["score"] == 100, clean
+    vague = lint("the ultimate guide to growth")
+    kinds = {k for k, _ in vague["issues"]}
+    assert {"vague", "specific"} <= kinds, vague
+    assert any(k == "front" for k, _ in lint("how is it done in 2026")["issues"])
+    assert lint("STOP DOING THIS NOW Please")["issues"][0][0] == "caps"
+    print("self-test ok")
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("file", nargs="?")
+    ap.add_argument("--title")
+    ap.add_argument("--thumb")
+    ap.add_argument("--json", action="store_true")
+    ap.add_argument("--self-test", action="store_true")
+    a = ap.parse_args()
+    if a.self_test:
+        return self_test()
+    if a.title:
+        rows = [lint(a.title, a.thumb)]
+    elif a.file:
+        rows = []
+        with open(a.file, encoding="utf-8") as fh:
+            for line in fh:
+                if line.strip():
+                    title, _, thumb = line.partition("|")
+                    rows.append(lint(title, thumb.strip() or None))
+    else:
+        ap.error("give --title or a file")
+    rows.sort(key=lambda r: -r["score"])
+    if a.json:
+        print(json.dumps(rows, indent=2))
+    else:
+        for r in rows:
+            show(r)
+
+
+if __name__ == "__main__":
+    main()

package/skills/youtube-planner/scripts/retention.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Read a YouTube Studio audience-retention export and find where viewers leave.
+
+Usage:
+  retention.py <retention.csv> [--duration <seconds>] [--transcript <file.srt|.vtt>] [--json]
+  retention.py --self-test
+
+Export: Studio > the video > Analytics > Engagement > audience retention chart >
+download > "Audience retention". Each row is a position (seconds, or percent of
+the video) and the percent still watching. Pass --duration when the position is
+a percent, so the opening and the cliffs come out in seconds.
+
+Three readings, three different fixes:
+  Hook leak  share lost in the first 30 seconds. Under 25 healthy, under 40 leaking, else severe.
+  Cliffs     the 5 steepest drops (points per second): a moment to look at.
+  Slide      average loss per second across the middle: pacing, fixed by cutting.
+Stdlib only. Reads local files, never the network.
+"""
+import argparse
+import csv
+import json
+import re
+
+HOOK_SECONDS = 30
+CLIFF_MIN = 0.8  # ponytail: fixed drop floor in points, scale by video length if short videos over-report
+
+
+def load_rows(path):
+    rows = []
+    with open(path, newline="", encoding="utf-8-sig", errors="replace") as fh:
+        for cells in csv.reader(fh):
+            nums = []
+            for c in cells:
+                try:
+                    nums.append(float(c.strip().replace("%", "").replace(",", "")))
+                except ValueError:
+                    pass
+            if len(nums) >= 2:
+                rows.append((nums[0], nums[1]))
+    return rows
+
+
+def to_seconds(rows, duration):
+    if duration and max(x for x, _ in rows) <= 100.5:
+        return [(x / 100 * duration, y) for x, y in rows]
+    return rows
+
+
+def load_cues(path):
+    text = open(path, encoding="utf-8-sig", errors="replace").read()
+    stamp = r"(\d+):(\d\d):(\d\d)[,.](\d+)"
+    cues = []
+    for block in re.split(r"\n\s*\n", text):
+        m = re.search(stamp + r"\s*-->\s*" + stamp, block)
+        if not m:
+            continue
+        g = [int(v) for v in m.groups()]
+        start = g[0] * 3600 + g[1] * 60 + g[2] + g[3] / 1000
+        end = g[4] * 3600 + g[5] * 60 + g[6] + g[7] / 1000
+        words = " ".join(line for line in block[m.end():].splitlines() if line.strip())
+        cues.append((start, end, re.sub(r"<[^>]+>", "", words)))
+    return cues
+
+
+def analyze(rows, cues=None):
+    start = rows[0][1]
+    opening = [y for x, y in rows if x <= HOOK_SECONDS]
+    hook_leak = start - min(opening) if opening else 0.0
+    band = "healthy" if hook_leak < 25 else "leaking" if hook_leak < 40 else "severe"
+    # steepest first: points lost per second, so a sharp drop beats a long gentle one
+    drops = [((rows[i - 1][1] - rows[i][1]) / ((rows[i][0] - rows[i - 1][0]) or 1),
+              rows[i - 1][1] - rows[i][1], rows[i - 1][0], rows[i][0]) for i in range(1, len(rows))]
+    cliffs = []
+    for _, lost, x0, x1 in sorted(drops, reverse=True):
+        if len(cliffs) == 5:
+            break
+        if lost < CLIFF_MIN:
+            continue
+        said = " ".join(c[2] for c in cues or [] if c[0] <= x0 + 4 and c[1] >= x0 - 4)
+        cliffs.append({"at": round(x0, 1), "to": round(x1, 1), "lost": round(lost, 2), "said": said[:160]})
+    middle = [r for r in rows if r[0] > HOOK_SECONDS]
+    span = middle[-1][0] - middle[0][0] if len(middle) > 1 else 0
+    slide = (middle[0][1] - middle[-1][1]) / span if span else 0.0
+    return {"start": start, "end": rows[-1][1], "hook_leak": round(hook_leak, 2), "hook_band": band,
+            "cliffs": cliffs, "slide_per_second": round(slide, 4)}
+
+
+def report(r):
+    print(f"Retention {r['start']:.1f}% -> {r['end']:.1f}%")
+    print(f"Hook leak: {r['hook_leak']:.1f} points lost in the first {HOOK_SECONDS}s [{r['hook_band']}]")
+    print("Cliffs:")
+    for c in r["cliffs"]:
+        said = f'  "{c["said"]}"' if c["said"] else ""
+        print(f"  -{c['lost']:.1f} at {c['at']:.0f}{said}")
+    if not r["cliffs"]:
+        print(f"  none over {CLIFF_MIN} points: the loss is slide, not moments")
+    print(f"Slide: {r['slide_per_second']:.3f} points per second across the middle")
+
+
+def self_test():
+    # 300s video in percent positions; a 6-point cliff at 15% (45s)
+    rows = [(0, 100), (5, 88), (10, 82), (15, 80), (20, 74), (40, 70), (60, 66), (80, 62), (100, 58)]
+    rows = to_seconds(rows, 300)
+    assert rows[3] == (45.0, 80)
+    cues = [(40.0, 46.0, "quick word from our sponsor"), (100.0, 104.0, "later")]
+    r = analyze(rows, cues)
+    assert r["hook_leak"] == 18 and r["hook_band"] == "healthy", r
+    assert r["cliffs"][0]["lost"] == 12 and r["cliffs"][0]["at"] == 0.0, r  # opening drop is steepest
+    cliff45 = next(c for c in r["cliffs"] if c["at"] == 45.0)
+    assert cliff45["lost"] == 6 and "sponsor" in cliff45["said"], r
+    assert r["slide_per_second"] == round((80 - 58) / 255, 4), r  # middle starts at 45s
+    assert analyze([(0, 100), (10, 55), (60, 50)])["hook_band"] == "severe"
+    print("self-test ok")
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("csv", nargs="?")
+    ap.add_argument("--duration", type=float)
+    ap.add_argument("--transcript")
+    ap.add_argument("--json", action="store_true")
+    ap.add_argument("--self-test", action="store_true")
+    a = ap.parse_args()
+    if a.self_test:
+        return self_test()
+    if not a.csv:
+        ap.error("csv is required")
+    rows = load_rows(a.csv)
+    if len(rows) < 8:
+        ap.error("need at least 8 data rows from the export")
+    rows = to_seconds(rows, a.duration)
+    if max(x for x, _ in rows) <= 100.5 and not a.duration:
+        print("Note: positions look like percents. Pass --duration for seconds; the hook window is approximate.")
+    r = analyze(rows, load_cues(a.transcript) if a.transcript else None)
+    if a.json:
+        print(json.dumps(r, indent=2))
+    else:
+        report(r)
+
+
+if __name__ == "__main__":
+    main()