rsc-universal 0.1.1

package/skills/youtube-packaging/scripts/verify.sh

@@ -0,0 +1,250 @@
+#!/usr/bin/env bash
+#
+# verify.sh — structural guardrail for an emitted YouTube package file.
+#
+# WHAT IT DOES (read-only; never edits or writes a file)
+#   Static, network-free checks over ONE package draft you point it at. The draft
+#   is plain text / markdown with labeled sections. Recognized labels (any case,
+#   English or ES/CA), one per line, the content following on the same or next
+#   lines until the next label:
+#     Titles:      title / titulo / títol / titulos / títols   (one title per line)
+#     Description: description / descripcion / descripció
+#     Tags:        tags / etiquetas / etiquetes
+#     Hashtags:    hashtags
+#     Chapters:    chapters / capitulos / capítols           (one "MM:SS Name" per line)
+#
+#   Checks:
+#     1. ≥ 2 titles present (the A/B set rule)             -> FAIL if < 2.
+#     2. Every title ≤ 100 chars                           -> FAIL per over-long title.
+#        Warn if a title opens with filler ("In this video"/"Welcome").
+#     3. Description above-fold first line present and
+#        ≤ 150 chars                                       -> FAIL if missing/over.
+#     4. Chapters: ≥ 3 timestamps, first is 0:00/00:00,
+#        ascending, each gap ≥ 10s                          -> FAIL with the broken rule.
+#     5. Hashtags: count ≥ 1 and ≤ 15 (>15 = all stripped) -> FAIL if > 15; warn if 0.
+#     6. Tags: ≥ 1 and the joined field ≤ 500 chars        -> FAIL if over budget.
+#
+#   A clean OR empty/whitespace-only file exits 0 — never a false failure.
+#   Missing OPTIONAL sections warn; only present-but-broken sections fail.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh package.md            # run all checks
+#   ./verify.sh package.md --strict   # treat warnings as failures (CI gate)
+#
+# EXIT CODES
+#   0  clean, warnings only (without --strict), or empty/missing-content file
+#   1  a hard failure — or any warning under --strict
+#   2  bad usage (no file given, or file does not exist)
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays, no bc.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() { sed -n '2,44p' "$0" | sed 's/^# \{0,1\}//'; }
+
+FILE=""
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) usage; exit 0 ;;
+    --strict) STRICT=1; shift ;;
+    -*) printf '%sunknown option: %s%s\n' "$RED" "$1" "$NC" >&2; usage; exit 2 ;;
+    *) if [ -z "$FILE" ]; then FILE="$1"; fi; shift ;;
+  esac
+done
+
+if [ -z "$FILE" ]; then
+  printf '%sno package file given%s\n' "$RED" "$NC" >&2; usage; exit 2
+fi
+if [ ! -f "$FILE" ]; then
+  printf '%sfile not found: %s%s\n' "$RED" "$FILE" "$NC" >&2; exit 2
+fi
+
+# Empty / whitespace-only file: nothing to check, do not false-fail.
+if [ ! -s "$FILE" ] || ! grep -q '[^[:space:]]' "$FILE" 2>/dev/null; then
+  ok "empty file — nothing to check"
+  exit 0
+fi
+
+printf 'youtube-packaging verify — %s\n\n' "$FILE"
+
+# --- section splitter ---------------------------------------------------------
+# Emit the content lines that belong to a given section label. Reads the file,
+# turns "on" at a matching label line, "off" at the next recognized label.
+LABELS_RE='^[[:space:]]*(titles?|titulos?|títols?|titulo|títol|description|descripcion|descripció|tags|etiquetas|etiquetes|hashtags|chapters|capitulos|capítols)[[:space:]]*:'
+
+section() {
+  # $1 = alternation of label tokens for the section to capture (no anchors)
+  awk -v want="$1" -v anylabel="$LABELS_RE" '
+    BEGIN { wantre = "^[[:space:]]*(" want ")[[:space:]]*:" }
+    {
+      line = $0
+      low  = tolower(line)
+      if (low ~ anylabel) {
+        # is this the label we want? (anchored: the whole token before the colon)
+        active = (low ~ wantre) ? 1 : 0
+        # if the label line carries inline content after the colon, keep it
+        rest = line
+        sub(/^[^:]*:[[:space:]]*/, "", rest)
+        if (active && rest ~ /[^[:space:]]/) print rest
+        next
+      }
+      if (active && line ~ /[^[:space:]]/) print line
+    }
+  ' "$FILE"
+}
+
+trim() { sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//'; }
+
+# --- 1 + 2. titles ------------------------------------------------------------
+TITLES="$(section 'titulos?|títols?|titles?|titulo|títol' | trim | grep -E '[^[:space:]]' || true)"
+TITLE_COUNT=0
+if [ -n "$TITLES" ]; then
+  TITLE_COUNT="$(printf '%s\n' "$TITLES" | grep -c '[^[:space:]]' || true)"
+fi
+
+if [ "${TITLE_COUNT:-0}" -lt 2 ]; then
+  fail "found ${TITLE_COUNT} title(s) — ship a SET of 2-3 titles for the A/B test, never one"
+else
+  ok "title set has ${TITLE_COUNT} titles (>= 2)"
+fi
+
+if [ -n "$TITLES" ]; then
+  while IFS= read -r t; do
+    [ -n "$t" ] || continue
+    tlen="$(printf '%s' "$t" | wc -m | tr -d '[:space:]')"
+    if [ "${tlen:-0}" -gt 100 ]; then
+      fail "title is ${tlen} chars (> 100 hard limit): ${t}"
+    fi
+    if printf '%s' "$t" | grep -Eiq '^[[:space:]]*(in this video|welcome to)'; then
+      warn "title opens with filler — front-load the keyword + hook: ${t}"
+    fi
+  done <<EOF
+$TITLES
+EOF
+fi
+
+# --- 3. description above-fold ------------------------------------------------
+DESC_FIRST="$(section 'description|descripcion|descripció' | grep -E '[^[:space:]]' | head -1 | trim || true)"
+if [ -z "$DESC_FIRST" ]; then
+  warn "no description section found — the above-fold line is the only part most viewers see"
+else
+  dlen="$(printf '%s' "$DESC_FIRST" | wc -m | tr -d '[:space:]')"
+  if [ "${dlen:-0}" -gt 150 ]; then
+    fail "description above-fold line is ${dlen} chars (> ~150) — only ~125 show before 'Show more'"
+  else
+    ok "description above-fold line present (${dlen} chars)"
+  fi
+fi
+
+# --- 4. chapters --------------------------------------------------------------
+CHAPTERS="$(section 'chapters|capitulos|capítols')"
+# collect timestamps as total seconds, in order
+STAMP_SECONDS=""
+STAMP_COUNT=0
+FIRST_STAMP=""
+if [ -n "$CHAPTERS" ]; then
+  while IFS= read -r line; do
+    ts="$(printf '%s' "$line" | grep -oE '([0-9]+:)?[0-9]{1,2}:[0-9]{2}' | head -1 || true)"
+    [ -n "$ts" ] || continue
+    [ -z "$FIRST_STAMP" ] && FIRST_STAMP="$ts"
+    # parse H:MM:SS or M:SS / MM:SS into seconds
+    h=0; m=0; s=0
+    case "$ts" in
+      *:*:*) h="${ts%%:*}"; rest="${ts#*:}"; m="${rest%%:*}"; s="${rest#*:}" ;;
+      *:*)   m="${ts%%:*}"; s="${ts#*:}" ;;
+    esac
+    total=$(( 10#$h * 3600 + 10#$m * 60 + 10#$s ))
+    STAMP_SECONDS="${STAMP_SECONDS}${total} "
+    STAMP_COUNT=$((STAMP_COUNT + 1))
+  done <<EOF
+$CHAPTERS
+EOF
+fi
+
+if [ "$STAMP_COUNT" -eq 0 ]; then
+  warn "no chapters section found — chapters lift watch time and add search jump-to targets"
+else
+  chap_fail=0
+  if [ "$STAMP_COUNT" -lt 3 ]; then
+    fail "chapters: only ${STAMP_COUNT} timestamp(s) — YouTube needs >= 3 or it ignores ALL chapters"
+    chap_fail=1
+  fi
+  case "$FIRST_STAMP" in
+    0:00|00:00|0:0|00:0|0:00:00) : ;;
+    *) fail "chapters: first timestamp is '${FIRST_STAMP}', not 00:00 — without 0:00 YouTube ignores ALL chapters"; chap_fail=1 ;;
+  esac
+  # ascending + >=10s gaps
+  prev=""
+  for sec in $STAMP_SECONDS; do
+    if [ -n "$prev" ]; then
+      if [ "$sec" -le "$prev" ]; then
+        fail "chapters: timestamps not strictly ascending (${prev}s then ${sec}s)"
+        chap_fail=1
+      elif [ $(( sec - prev )) -lt 10 ]; then
+        fail "chapters: a chapter is shorter than 10s (${prev}s -> ${sec}s)"
+        chap_fail=1
+      fi
+    fi
+    prev="$sec"
+  done
+  [ "$chap_fail" -eq 0 ] && ok "chapters: ${STAMP_COUNT} timestamps, first 00:00, ascending, gaps >= 10s"
+fi
+
+# --- 5. hashtags --------------------------------------------------------------
+HASHTAG_BLOCK="$(section 'hashtags' || true)"
+# count '#word' tokens across the hashtag section (fallback: whole file's # tokens)
+if [ -z "$(printf '%s' "$HASHTAG_BLOCK" | grep -E '[^[:space:]]' || true)" ]; then
+  HASHTAG_BLOCK="$(grep -oE '#[A-Za-z0-9_]+' "$FILE" || true)"
+fi
+HASHTAG_COUNT="$(printf '%s\n' "$HASHTAG_BLOCK" | grep -oE '#[A-Za-z0-9_]+' | grep -c '#' || true)"
+if [ "${HASHTAG_COUNT:-0}" -eq 0 ]; then
+  warn "no hashtags found — 3-5 relevant hashtags help discovery; the first 3 show above the title"
+elif [ "${HASHTAG_COUNT:-0}" -gt 15 ]; then
+  fail "found ${HASHTAG_COUNT} hashtags (> 15) — YouTube strips ALL hashtags over 15"
+else
+  ok "hashtags within limit (${HASHTAG_COUNT}, 1-15)"
+fi
+
+# --- 6. tags ------------------------------------------------------------------
+TAGS="$(section 'tags|etiquetas|etiquetes' | grep -E '[^[:space:]]' | trim || true)"
+if [ -z "$TAGS" ]; then
+  warn "no tags section found — add 5-8 tags, first = exact target phrase"
+else
+  # join into one field (comma or newline separated) and measure char budget
+  TAGS_JOINED="$(printf '%s' "$TAGS" | tr '\n' ',')"
+  TAGLEN="$(printf '%s' "$TAGS_JOINED" | wc -m | tr -d '[:space:]')"
+  if [ "${TAGLEN:-0}" -gt 500 ]; then
+    fail "tags field is ${TAGLEN} chars (> ~500 budget) — trim the tag list"
+  else
+    ok "tags present, field ${TAGLEN} chars (<= ~500)"
+  fi
+fi
+
+# --- summary ------------------------------------------------------------------
+printf '\n'
+if [ "$fail_count" -gt 0 ]; then
+  printf '%s%d hard failure(s), %d warning(s)%s\n' "$RED" "$fail_count" "$warn_count" "$NC"
+  exit 1
+fi
+if [ "$warn_count" -gt 0 ]; then
+  if [ "$STRICT" -eq 1 ]; then
+    printf '%s%d warning(s) — failing under --strict%s\n' "$YELLOW" "$warn_count" "$NC"
+    exit 1
+  fi
+  printf '%s%d warning(s), 0 hard failures%s\n' "$YELLOW" "$warn_count" "$NC"
+  exit 0
+fi
+printf '%sall checks passed%s\n' "$GREEN" "$NC"
+exit 0

package/skills/youtube-strategy/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: youtube-strategy
+description: "Use when a YouTube channel needs a SYSTEM-level decision — positioning/niche, upload cadence, how videos chain into playlists and series, end-screen routing, or a 'what's working, what to do more of' review — read from and written back to the channel's own learning wiki, not one video's choices. Triggers: 'what should my channel be about', 'who is my channel for', 'how often should I post', 'should I niche down or stay broad', 'organize my videos so people binge several in a row', 'my end screens aren't keeping people watching', 'quarterly channel review what's working', 'qué temática para mi canal de YouTube', 'cada cuánto subo vídeos'. NOT generating next-video topics/hooks (that is youtube-ideation), NOT per-video titles/thumbnail-text (that is youtube-packaging), NOT designing the thumbnail image (that is youtube-thumbnails), NOT fetching metrics from the Data API (that is youtube-api)."
+tags: [youtube, channel-strategy, positioning, cadence, playlists, retention]
+recommends: [youtube-ideation, youtube-packaging, youtube-api, content-engine, decision-records]
+origin: risco
+---
+
+# YouTube Strategy — The Channel as a System, Not the Next Video
+
+*You operate at channel/portfolio altitude.* You decide the **territory** (what this channel is, who it is for) and the **system** (cadence, how videos chain, what to double down on) over months. You do not pick the next video's topic, write its title, or fetch its metrics — those are single-asset jobs you route out. Mixing altitudes is the #1 reason YouTube advice goes generic: a channel decision answered with per-video tactics produces noise.
+
+Your spine is a read/write loop with the channel's own history. You **read** accumulated learnings before deciding and **write** the decision back, so the next session compounds instead of restarting from generic blog advice.
+
+## Altitude boundary — route single-asset work out
+
+| The ask | Skill | Why it is not you |
+|---|---|---|
+| Topics/hooks for the next upload | `../youtube-ideation/SKILL.md` | You set the territory; ideation fills it. |
+| Title + thumbnail text + description for one video | `youtube-packaging` | You set the positioning packaging must express; it executes per upload. |
+| The thumbnail image itself | `../youtube-thumbnails/SKILL.md` | Image design is a craft asset, not a channel decision. |
+| Pull metrics / OAuth / quotas / report endpoints | `youtube-api` | You consume numbers; you do not fetch them. |
+| Render or edit the video | `remotion-video` | Production, not strategy. |
+| Cross-platform calendar / scheduling | `../content-engine/SKILL.md`, `../social-publisher/SKILL.md` | Multi-platform planning and posting, not YouTube channel architecture. |
+
+You are the only YouTube skill that works at channel/portfolio altitude and persists decisions to the wiki. Every sibling works on a single asset.
+
+## The wiki loop comes FIRST (this is the spine)
+
+Before any strategy decision, **READ** `02-DOCS/wiki/youtube/`. *Why: a strategy decision made without the channel's own retention/CTR history regresses to generic advice that ignores what this specific audience rewards.*
+
+Extract, in order:
+1. **Prior positioning** — what the channel claimed to be, and whether it held.
+2. **Current cadence + whether it held** — the stated rate and whether quality dropped at it.
+3. **Top retention/CTR performers** — which videos/playlists earned the watch time, and what they share.
+4. **Killed experiments** — series or formats already sunset, so you do not re-propose a dead bet.
+
+If `02-DOCS/wiki/youtube/` is empty or absent → **bootstrap it**: create the directory and a positioning stub, then proceed. Do not skip the loop because the dir is missing — create it and start the record now. Layout and templates are in `references/wiki-records.md`.
+
+Cite what you grounded in (e.g. "cadence held at 2/wk per `02-DOCS/wiki/youtube/decisions/2026-03-cadence.md`"). If you grounded in nothing because the wiki was empty, say so and say you are bootstrapping.
+
+## Positioning & niche
+
+Positioning sits at a **three-factor intersection**. Pick the niche where all three overlap:
+
+- **Sustained interest** — you can make 100+ videos here without burning out. *Why: cadence dies the moment the topic bores the creator.*
+- **Measurable audience demand** — searches/views exist for it. *Why: passion without demand is a diary.*
+- **Monetization potential** — CPM and competition leave room. *Why: a niche with no advertiser value caps the channel's ceiling regardless of views.*
+
+(TubeBuddy; OutlierKit CPM-ranked niches, 2026.)
+
+**Niche down 2–3 levels.** "Gaming / cooking / tech" are *industries*, not niches. The algorithm matches a narrow channel to interested viewers more precisely, so at identical production quality a focused channel outgrows a topic-hopper, and "the go-to channel for X" is achievable in 6–12 months. Walk the ladder:
+
+```text
+industry   →  category          →  angle                    →  who-it's-for
+tech       →  keyboards         →  budget mechanical boards  →  programmers who type all day
+gaming     →  roguelikes        →  honest sub-$20 reviews    →  players who buy on a budget
+```
+
+- Bad: "a tech channel." (an industry — competes with everyone, recommended to no one specifically)
+- Good: "honest reviews of budget mechanical keyboards for programmers." (a defensible go-to position)
+
+**Broad vs narrow — decide by stage and goal:**
+
+| Channel stage / goal | Lean | Why |
+|---|---|---|
+| New, <1k subs, finding fit | Narrow hard | Precision recommendation beats reach; you need a foothold, not a category. |
+| Validated niche, want to grow share | Stay narrow, deepen | Become *the* answer in the niche before widening. |
+| Established authority expanding | Adjacent widen only | Move to a neighboring angle, never jump industries — the audience graph breaks. |
+| Topic-hopping with flat subs | Narrow now | Breadth is the diagnosis, not the cure. |
+
+## Cadence
+
+**Rule: pick the highest rate you can hold for 8 weeks without a quality drop.** *Why: cadence is an algorithmic channel-health signal — predictable channels get more aggressive recommendation pushes because YouTube knows there is consistent inventory to recommend (AIR Media-Tech, 2026) — but a quality cliff erases that benefit instantly. Consistency of strong videos beats raw frequency.*
+
+Baselines, used as a starting frame, **then corrected by the wiki's own retention data, not by a blog number**:
+
+- New channels: **1–2/week.**
+- Many mid-size channels validate at **2–4/week.**
+
+Run the gate before committing to a rate. If any answer is "no," step the cadence down a notch:
+
+- [ ] Can the team sustain this rate for 8 weeks with no degradation in idea, script, or thumbnail quality?
+- [ ] Is the idea backlog deep enough to feed it (no scraping-the-barrel uploads)?
+- [ ] Is there thumbnail/packaging bandwidth for every slot at this rate?
+
+If wiki retention shows watch time falling while cadence held steady, the problem is not "post more" — it is idea/packaging/structure (see the review loop). Raising cadence on a quality problem accelerates the decline.
+
+## Channel architecture — playlists, series, end screens
+
+The algorithm scores **session** watch time — whether your video extends the viewer's stay on the platform — and pushes channels that reliably start or extend sessions (SolveigMM, 2025). So you do not design videos in isolation; you design **chains**.
+
+- **Playlists are binge paths, not folders.** A playlist titled to promise a journey ("Build a SaaS from zero") outperforms a dumping ground ("My videos 2026"). Strategic playlists + end screens can lift session time ~10–30% (Boss Wallah; Gyre, 2026).
+- **Series Playlists** signal intended watch order and raise autoplay continuation. Use them when sequence matters.
+- **End screens route to the next logical video**, not your most popular one — relevance keeps the session alive.
+
+The reliable shape is a deliberate sequence:
+
+```text
+Part 1 (hook + promise)  →  Part 2 (payoff)  →  Case Study (proof)  →  Q&A (depth)
+```
+
+Each step end-screens to the next; the playlist holds them in order. Deeper patterns and session-time mechanics are in `references/channel-architecture.md`.
+
+## Review & double-down loop
+
+A review is not "are views up." It is reading the wiki to find the rising signal and acting on it:
+
+```text
+Read what-worked + retention notes
+        │
+   Is watch time rising while cadence held steady?
+        │
+   ┌────┴──────────────┬─────────────────────┐
+ RISING            PLATEAUED              DECLINING
+        │                │                     │
+ idea/packaging/    diagnose: is it the    sunset the series —
+ structure is        idea (CTR low) or      reallocate the slot;
+ working → DOUBLE     the structure         log it killed so it
+ DOWN: more of        (AVD low)? route       is never re-proposed
+ that format/angle    the weak half out
+```
+
+Read CTR (>~6% is healthy for new channels) and AVD/retention from the wiki to choose the next bet (EntreResource; AIR Media-Tech, 2026). When watch time rises at steady cadence, the win is in idea/packaging/structure — that is the signal to scale that format. Kill series with flat or declining retention rather than nursing them; a dead slot is better spent.
+
+## Write the decision back (on exit, always)
+
+A strategy session that does not write back does not compound — the next session starts from zero. On exit, append a **dated decision record** under `02-DOCS/wiki/youtube/` and, when reviewing, a **what-worked** entry tied to specific videos/playlists. Minimal record inline; full templates in `references/wiki-records.md`:
+
+```markdown
+# 2026-06-02 — Niche down to budget mechanical keyboards for programmers
+- Context read: flat subs at 40 videos; top 3 by AVD all keyboard reviews (wiki/youtube/what-worked.md)
+- Decision: reposition from "tech reviews" to "budget mechanical keyboards for programmers"; cadence 2/wk held
+- Bets on metric: AVD on keyboard videos (currently ~48%) holding while non-keyboard topics are dropped
+- Review date: 2026-09-02
+```
+
+Every record names **the metric it is betting on** and a **review date**. A decision with no metric is an opinion, not a bet you can later check. Run `scripts/verify.sh 02-DOCS/wiki/youtube/` after writing to confirm the records are structurally complete.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| Chasing daily uploads | Hits the quality cliff; weak inventory drags the whole channel's recommendation health | Pick the rate you can hold 8 weeks at quality |
+| Copying another channel's cadence | Their data is not yours; their audience rewards different things | Set cadence from your own wiki retention |
+| Treating playlists as storage folders | No binge promise, no session lift | Build titled binge paths and series in watch order |
+| Positioning as an industry ("a tech channel") | Competes with everyone, recommended to no one | Niche down 2–3 levels to a defensible angle |
+| Deciding without reading the wiki | Regresses to generic blog advice that ignores this audience | READ `02-DOCS/wiki/youtube/` before any decision |
+| Never writing the decision back | No compounding; every session restarts from zero | Append a dated record + the metric it bets on |
+| "Post more" to fix falling retention | Accelerates the decline; the problem is idea/structure | Diagnose CTR vs AVD; fix the weak half |
+| Jumping industries to grow | Breaks the audience graph; old subs churn | Widen only into adjacent angles |
+
+## References & routing
+
+- `references/wiki-records.md` — file layout under `02-DOCS/wiki/youtube/`, the decision-record and what-worked templates, and what `verify.sh` checks.
+- `references/channel-architecture.md` — deeper playlist/Series-Playlist/end-screen patterns, session-time mechanics, and binge-sequence examples.
+- Route out: next-video ideas → `../youtube-ideation/SKILL.md`; per-video packaging → `youtube-packaging`; raw metrics → `youtube-api`; decision-record discipline → `decision-records`.

package/skills/youtube-strategy/evals/README.md

@@ -0,0 +1,5 @@
+# Evals — youtube-strategy
+
+`cases.yaml` holds three groups. `should_trigger` lists channel-level prompts (positioning, cadence, playlist/series/end-screen architecture, "what's working" reviews, plus a Spanish and a no-keyword phrasing) that must load this skill. `should_not_trigger` lists single-asset prompts that must route to a real sibling instead (`youtube-ideation`, `youtube-packaging`, `youtube-thumbnails`, `youtube-api`, `social-publisher`). `capability` is one end-to-end scenario with a `must_include` rubric covering the read-wiki-first loop, three-factor positioning, data-driven cadence, a session-time architecture move, and writing a dated decision record back to the wiki.
+
+There is no automated runner in this repo. Run it by hand or with the catalog harness: feed each `should_trigger`/`should_not_trigger` prompt to the router and confirm the routing matches; for `capability`, run the scenario against the skill and score the output against every `must_include` line (each is pass/fail). The artifact discipline is separately checked by `../scripts/verify.sh` against a real `02-DOCS/wiki/youtube/` tree.

package/skills/youtube-strategy/evals/cases.yaml

@@ -0,0 +1,61 @@
+skill: youtube-strategy
+
+# Prompts that MUST load `youtube-strategy`. This skill works at CHANNEL/portfolio
+# altitude: positioning/niche, upload cadence, how videos chain into playlists/series,
+# end-screen routing for session time, and "what's working" reviews — read from and
+# written back to 02-DOCS/wiki/youtube/. It does NOT generate per-video topics/hooks
+# (youtube-ideation), per-video titles/thumbnail-text (youtube-packaging), thumbnail
+# images (youtube-thumbnails), or fetch metrics from the Data API (youtube-api).
+should_trigger:
+  - prompt: "Should I niche down or keep my channel broad?"
+    why: "Core positioning decision — broad-vs-narrow at channel altitude is exactly what this skill owns."
+
+  - prompt: "How often should I be uploading given my retention is dropping?"
+    why: "Cadence decision tied to the channel's own retention data, not a generic number — the skill's data-driven cadence call."
+
+  - prompt: "Organize my videos so new viewers binge several in a row."
+    why: "Non-obvious: no 'strategy' word, but it is playlist/series/end-screen session-time architecture, owned here."
+
+  - prompt: "Quarterly channel review — what's working and what should I do more of?"
+    why: "The read-wiki + double-down loop; reading what-worked and choosing the next bet is the skill's spine."
+
+  - prompt: "Qué temática debería tener mi canal de YouTube y cada cuánto subo vídeos?"
+    why: "Spanish for 'what topic should my YouTube channel have and how often do I upload' — positioning + cadence, both channel-level."
+
+  - prompt: "My end screens aren't keeping people watching — how should I route them?"
+    why: "Session-time architecture (end-screen routing to the next logical video) is a channel-system decision, not a per-video edit."
+
+should_not_trigger:
+  - prompt: "Give me 10 video ideas and hooks for next week's uploads."
+    route_to: youtube-ideation
+    why: "Generating specific topics/hooks fills the territory; strategy decides the territory but does not generate the ideas."
+
+  - prompt: "Write the title and thumbnail text for this upload."
+    route_to: youtube-packaging
+    why: "Per-video click optimization (title + thumbnail text + description) is packaging; strategy sets positioning, packaging expresses it per upload."
+
+  - prompt: "Design the thumbnail image for my new video."
+    route_to: youtube-thumbnails
+    why: "Designing the image is a craft asset job, not a channel-system decision."
+
+  - prompt: "Pull my last 28 days of watch-time data from the YouTube API."
+    route_to: youtube-api
+    why: "Fetching metrics, OAuth, quotas, report endpoints is the data plumbing; strategy consumes the numbers, it does not fetch them."
+
+  - prompt: "Schedule and cross-post this video to TikTok and Instagram too."
+    route_to: social-publisher
+    why: "Cross-platform scheduling/posting is social-publisher; strategy is YouTube channel architecture, not multi-platform distribution."
+
+capability:
+  - scenario: >
+      A channel has 40 videos and flat subscriber growth. 02-DOCS/wiki/youtube/
+      already contains retention and CTR notes (the top 3 videos by AVD are all
+      keyboard reviews) and current cadence of 2/week that held. Produce a strategy
+      decision for where this channel should go next.
+    must_include:
+      - "Reads 02-DOCS/wiki/youtube/ first (prior positioning, whether cadence held, top retention/CTR performers, killed experiments) — or bootstraps the dir if it were empty"
+      - "Gives a positioning/niche-down recommendation grounded in the three factors (interest x demand x monetization), narrowing 2-3 levels from an industry to a defensible angle"
+      - "Gives a cadence recommendation justified by the channel's own retention data (e.g. hold 2/wk since it held at quality), not a generic blog number, and applies the 8-week sustainability gate"
+      - "Proposes at least one playlist/Series-Playlist/end-screen move for session time (e.g. a binge chain built around the keyboard format that already earns the best AVD)"
+      - "Writes a dated decision record back to 02-DOCS/wiki/youtube/ that names the single metric it bets on and a review date"
+      - "Routes single-asset work out: next-video ideas to youtube-ideation, per-video packaging to youtube-packaging, raw metrics to youtube-api"

package/skills/youtube-strategy/references/channel-architecture.md

@@ -0,0 +1,46 @@
+# Channel architecture — chains that extend the session
+
+The algorithm scores **session watch time**: whether a viewer who lands on your video stays on the platform longer because of it. A 12-minute video with great per-video retention that dumps the viewer back to the home feed is worth less than a good-enough video that hands them to the next one. Design chains, not isolated assets. (SolveigMM, "How the YouTube algorithm works in 2025"; Boss Wallah playlist strategy, 2026; Gyre end-screen guide, 2026.)
+
+## Playlists as binge paths
+
+A playlist is a promise of a journey, not a storage bin.
+
+- **Title the promise, not the contents.** "Build a SaaS from zero to first customer" beats "SaaS videos." The title sells the binge.
+- **Order for momentum.** First video is the strongest hook; each subsequent one pays off the prior. Front-load the win.
+- **One playlist = one outcome.** If a viewer cannot say what they will be able to do after finishing it, the playlist is a folder.
+
+## Series Playlists
+
+Series Playlists explicitly mark intended watch order. YouTube then signals "next in series," which raises autoplay continuation. Use them when sequence genuinely matters (a build-along, a course, a multi-part teardown). Do not mark an unordered topic collection as a series — the broken sequence promise hurts more than it helps.
+
+## End-screen routing
+
+End screens are routing, not decoration. The default mistake is routing every video to your single most popular upload.
+
+- **Route to the next logical video**, the one this viewer most likely wants next given what they just watched. Relevance sustains the session; a popular-but-unrelated link breaks it.
+- **Two elements max** in the last ~20 seconds: the next video + (optionally) the playlist that contains it. More choices lower the click.
+- **Match the end screen to the chain position.** Part 1 ends to Part 2, not to the channel trailer.
+
+Strategic playlists plus relevant end screens can lift session time roughly **10–30%** (Boss Wallah; Gyre, 2026). That lift is a channel-health signal, not a per-video one — it compounds across the catalog.
+
+## The reliable binge sequence
+
+```text
+Part 1            Part 2          Case Study        Q&A
+hook + promise →  the payoff   →  proof it works →  depth / objections
+   │ end-screen      │ end-screen     │ end-screen       │ end-screen
+   ▼                 ▼                ▼                  ▼
+ Part 2           Case Study        Q&A             related playlist
+```
+
+Each node end-screens to the next; a Series Playlist holds all four in order. The sequence works because it mirrors how interest deepens: curiosity → resolution → evidence → mastery.
+
+## Concrete examples
+
+| Niche | Binge sequence | Why it chains |
+|---|---|---|
+| Budget keyboards for programmers | "5 sub-$20 boards tested" → "The one I kept after 3 months" → "Building my programmer setup around it" → "Your keyboard questions answered" | Comparison hooks, then long-term proof, then application, then objections |
+| SaaS build-along | "Idea to landing page" → "First paid feature" → "How I got 10 customers" → "What I'd do differently" | Each step is the next thing the same viewer needs |
+
+When picking which chain to invest in, read `what-worked.md`: build the sequence around the format that already earns the channel's best AVD, not around what you wish performed.

package/skills/youtube-strategy/references/wiki-records.md

@@ -0,0 +1,86 @@
+# Wiki records — the read/write loop on disk
+
+This is where the channel's strategy memory lives. The skill READs it on entry and WRITEs to it on exit so sessions compound. Keep it append-only.
+
+## File layout under `02-DOCS/wiki/youtube/`
+
+```text
+02-DOCS/wiki/youtube/
+├── positioning.md            # current claim: niche, who-it's-for, the three-factor rationale
+├── what-worked.md            # running log of wins/losses tied to specific videos/playlists
+└── decisions/                # one dated file per strategy decision (append-only)
+    ├── 2026-03-cadence.md
+    └── 2026-06-niche-down.md
+```
+
+- `positioning.md` is the single living statement of what the channel is. Overwrite it when positioning changes, but record the change as a decision file.
+- `decisions/` is never edited after the fact — supersede an old decision with a new dated file, do not rewrite history. *Why: the value is the audit trail of what was tried and what it bet on.*
+- A single running `decisions.md` log is acceptable for small channels instead of per-file; `verify.sh` accepts either.
+
+## Bootstrap (empty or absent dir)
+
+When `02-DOCS/wiki/youtube/` does not exist, create it and a positioning stub before deciding anything:
+
+```bash
+mkdir -p 02-DOCS/wiki/youtube/decisions
+```
+
+`positioning.md` stub:
+
+```markdown
+# Channel positioning
+- Niche: <to define — narrow 2-3 levels, not an industry>
+- Who it's for: <specific viewer>
+- Three-factor check: interest=<>, demand=<>, monetization=<>
+- Last reviewed: <date>
+```
+
+## Decision-record template
+
+Every decision file carries these fields. The metric line is mandatory — a decision with no metric is an opinion, not a checkable bet.
+
+```markdown
+# <YYYY-MM-DD> — <one-line decision title>
+- Context read: <what the wiki/data said that drove this; cite files>
+- Decision: <positioning / cadence / series choice, stated concretely>
+- Bets on metric: <the single metric this decision expects to move, with current value>
+- Review date: <YYYY-MM-DD — when to check whether the bet paid off>
+```
+
+Worked example:
+
+```markdown
+# 2026-06-02 — Niche down to budget mechanical keyboards for programmers
+- Context read: flat subs at 40 videos; top 3 by AVD all keyboard reviews (what-worked.md)
+- Decision: reposition from "tech reviews" to "budget mechanical keyboards for programmers"; hold cadence 2/wk
+- Bets on metric: AVD on keyboard videos (~48%) holds while non-keyboard topics are dropped
+- Review date: 2026-09-02
+```
+
+## What-worked template
+
+Append one entry per observed win or loss, tied to a real asset so future sessions can pattern-match.
+
+```markdown
+## <YYYY-MM-DD> — <video or playlist id/title>
+- Metric: <CTR / AVD / session lift, with the number>
+- Lesson: <the transferable insight — what to do more or less of>
+```
+
+Example:
+
+```markdown
+## 2026-05-20 — "I Tested 5 Sub-$20 Keyboards" (vid abc123)
+- Metric: CTR 9.1%, AVD 52% (channel best)
+- Lesson: comparison + price ceiling in the title; double down on multi-product budget comparisons
+```
+
+## What `verify.sh` checks
+
+`scripts/verify.sh 02-DOCS/wiki/youtube/` is a read-only structural lint, no network:
+
+1. The target `02-DOCS/wiki/youtube/` directory exists.
+2. At least one decision record is present (a `decisions/*.md` file or a `decisions.md` log).
+3. Each decision record contains the three required signals: a date, a `Decision:` line, and a named metric/bet (a `Bets on metric:` line or equivalent `metric`/`bet` field).
+
+A record missing the metric field is a hard failure with a clear message. An empty or missing target reports cleanly and exits 0 — no false failure on a fresh channel.