@damiangilgonzalez/harness 1.3.7

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

@@ -0,0 +1,48 @@
+skill: youtube-packaging
+
+should_trigger:
+  - prompt: "Write the title and description for my new tutorial video."
+    why: Core packaging ask — the text fields of the upload.
+  - prompt: "Give me 3 title options to A/B test for this video."
+    why: Title SET / Test & Compare hypothesis, the signature output rule.
+  - prompt: "Add chapters with timestamps to my video description."
+    why: Chapters mechanics — the four exact rules live here.
+  - prompt: "My video's CTR is terrible and the title just isn't landing — fix it."
+    why: Non-obvious — a CTR complaint with no 'title/description' keyword leading; the rescue case for the words on the upload.
+  - prompt: "Log how the last upload performed and apply the lesson to the next package."
+    why: Non-obvious — the learning loop, reading the docs feedback log and carrying winners forward.
+  - prompt: "Escríbeme el título, la descripció i els hashtags del vídeo i afegeix capítols."
+    why: Catalan/Spanish — full metadata write (title, description, hashtags, chapters).
+
+should_not_trigger:
+  - prompt: "Design a thumbnail image for this video."
+    route_to: youtube-thumbnails
+    why: The picture, not the text fields — co-owned hypothesis but image work is the sibling's.
+  - prompt: "What video should I make next? Give me ideas for my channel."
+    route_to: youtube-ideation
+    why: The idea/angle, which packaging consumes but never invents.
+  - prompt: "Programmatically update the title and description via the YouTube Data API."
+    route_to: youtube-api
+    why: The API call/plumbing, not the copy.
+  - prompt: "Build my channel growth plan and posting cadence."
+    route_to: youtube-strategy
+    why: Channel-level strategy, not a single video's metadata.
+  - prompt: "Do keyword research for our website blog so it ranks on Google."
+    route_to: seo-geo
+    why: Non-YouTube web/AI-search SEO, a different surface entirely.
+
+capability:
+  - scenario: >
+      Here is a video: a 12-minute beginner Python tutorial. The channel's last 5
+      uploads are logged in docs with their title sets, CTR, and avg view
+      duration. Package this upload.
+    must_include:
+      - "Grounds in docs first: reads the channel brand voice and the feedback log, and carries a prior winner forward into the new set."
+      - "Emits a SET of 2-3 titles framed as an A/B hypothesis, each ≤100 chars with the keyword + hook in the first ~60 chars / first 5 words."
+      - "Above-the-fold description first line ≤ ~150 chars containing the primary keyword + who-it's-for."
+      - "Full description ~200-350 words of natural prose (no keyword stuffing), plus a links block and a 3-5 hashtag line."
+      - "Chapters obey all four rules: ≥3 timestamps, first is 00:00, each ≥10s, ascending order."
+      - "5-8 tags with the first tag = the exact target phrase, and notes tags' minimal ranking impact."
+      - "Appends/updates a feedback-log entry in docs for this package."
+      - "Routes the thumbnail image to youtube-thumbnails, the idea to youtube-ideation, and any API upload to youtube-api."
+      - "States that the A/B winner is chosen by watched-time-per-impression, not raw CTR."

package/skills/youtube-packaging/references/description-and-chapters.md

@@ -0,0 +1,203 @@
+# Description, chapters & feedback-log formats
+
+Offloaded depth for [../SKILL.md](../SKILL.md). Four things live here: the full
+description template with a filled example, the chapter format spec with the four
+failure cases worked through, the feedback-log entry schema with a filled row, and
+the OKF v0.1 frontmatter shape for the package and log when persisted into the wiki.
+
+## 1. Description template
+
+Structure every description in this order. Only the first ~125 chars are
+above-the-fold, so the first line carries the keyword and the audience.
+
+```text
+<ABOVE-FOLD LINE: primary keyword + who-it's-for, ~100-150 chars max>
+
+<BODY: 2-4 short paragraphs, ~200-350 words total. Natural prose. Weave the
+primary keyword + 1-2 variants in once each. Say what the video covers and the
+payoff. No keyword lists.>
+
+🔗 Resources
+- <link 1>
+- <link 2>
+
+▶️ Watch next: <link to a relevant video>
+
+👉 Subscribe for <one concrete promise>
+
+#hashtag1 #hashtag2 #hashtag3
+```
+
+### Filled example (12-minute beginner Python tutorial)
+
+```text
+Learn Python from scratch in 2026 — a 12-minute beginner tutorial that takes you
+from zero to your first working program, no prior coding needed.
+
+In this beginner Python tutorial you'll install Python, write your first function,
+and fix the error every newcomer hits. By the end you'll have a small program
+running on your own machine and a clear path to the next step. I keep the jargon
+out and the typing in — you build alongside me the whole way. If you've bounced off
+Python before because tutorials moved too fast, this one is paced for a true
+beginner.
+
+🔗 Resources
+- Starter code: https://example.com/python-starter
+- Free cheat sheet: https://example.com/python-cheatsheet
+
+▶️ Watch next: Python Projects for Beginners — https://example.com/next
+
+👉 Subscribe for one beginner-friendly coding tutorial every week.
+
+#Python #LearnToCode #ProgrammingForBeginners
+```
+
+The above-fold line is 132 characters — under the ~150 ceiling, keyword
+("Learn Python") first, audience ("beginner") explicit. The body is ~150 words of
+natural prose (scale to 200-350 for a longer video). Exactly 3 hashtags, all shown
+above the title.
+
+## 2. Chapter format spec
+
+Four rules, all enforced by YouTube. Break ANY one and every chapter is ignored.
+
+1. **≥ 3 timestamps.**
+2. **First timestamp is `00:00`.**
+3. **Each chapter ≥ 10 seconds long.**
+4. **Ascending order.**
+
+Compliant block:
+
+```text
+00:00 Intro — what you'll build
+00:42 Installing the tools
+03:15 Writing your first function
+07:50 Debugging the common error
+11:20 Recap & next steps
+```
+
+### The four failure cases
+
+```text
+# FAIL 1 — no 00:00 first (the silent killer): ALL chapters ignored
+00:42 Installing the tools
+03:15 Writing your first function
+07:50 Debugging
+Fix: add a 00:00 first line.
+
+# FAIL 2 — only 2 timestamps: below the 3 minimum, chapters do not render
+00:00 Intro
+05:00 Outro
+Fix: add at least one more chapter.
+
+# FAIL 3 — a chapter shorter than 10s: 00:05 -> 00:11 is only 6s
+00:00 Intro
+00:05 Setup
+00:11 Demo
+Fix: no two adjacent timestamps closer than 10 seconds.
+
+# FAIL 4 — out of order: 03:15 precedes 00:42
+00:00 Intro
+03:15 Demo
+00:42 Setup
+Fix: sort ascending.
+```
+
+Use `M:SS` or `MM:SS`; for videos over an hour use `H:MM:SS`. Each chapter title
+should be short and scannable — it doubles as a search jump-to target.
+
+## 3. Feedback-log entry schema
+
+One markdown table in `docs/wiki/youtube/packaging-log.md`. One row per A/B
+test, appended when Test & Compare resolves (~2 weeks).
+
+`docs/wiki/` is an **OKF v0.1** bundle, so `packaging-log.md` carries
+file-level frontmatter once at the top (a non-empty `type` plus the OKF surface
+shared across all four youtube skills), then the table below it. Refresh
+`timestamp` when you append a row; past rows are immutable.
+
+```markdown
+---
+type: youtube-package
+title: Packaging feedback log
+description: One row per Test & Compare result — title sets tried, winner, and the transferable lesson.
+tags: [youtube, packaging-log, ab-testing]
+timestamp: 2026-05-28T00:00:00Z
+---
+# Packaging feedback log
+
+| date | video | title set tried | winner | CTR | impressions | avg view duration | note |
+|------|-------|-----------------|--------|-----|-------------|-------------------|------|
+```
+
+> Note: this frontmatter is for the **persisted wiki file**. The package *draft*
+> you point `scripts/verify.sh` at uses labeled sections (`Titles:`,
+> `Description:`, …) and stays frontmatter-free so the linter parses it cleanly.
+
+Column meanings:
+
+| Column | Meaning |
+|---|---|
+| `date` | resolution date of the test (YYYY-MM-DD) |
+| `video` | video title slug or ID |
+| `title set tried` | the 2-3 titles entered into Test & Compare, `\|`-separated |
+| `winner` | which title YouTube auto-applied |
+| `CTR` | click-through rate of the winner (%) |
+| `impressions` | impressions over the test window |
+| `avg view duration` | average view duration (mm:ss) — the retention half |
+| `note` | the transferable lesson (the pattern, not the data point) |
+
+Filled row:
+
+```text
+| date | video | title set tried | winner | CTR | impressions | avg view duration | note |
+|------|-------|-----------------|--------|-----|-------------|-------------------|------|
+| 2026-05-28 | python-beginner-tut | Learn Python in 2026: 12-Min Beginner Tutorial \| Python in 12 Minutes (Total Beginner) \| I Taught a Beginner Python in 12 Min | Learn Python in 2026: 12-Min Beginner Tutorial | 7.8% | 41,200 | 04:31 | Numeric + year title beat curiosity title again (3rd time) — keep leading with the number on tutorials |
+```
+
+The `note` column is the point: it turns one data row into a prior the next
+package carries forward. Always grade the winner by watched-time-per-impression
+(reflected in CTR *and* avg view duration together), never CTR alone — a high-CTR /
+low-duration row is a warning, not a win.
+
+## 4. Persisted package — the wiki file
+
+When you persist a finished package under `docs/wiki/youtube/` (e.g.
+`packages/<video-slug>.md`), wrap it in OKF v0.1 frontmatter — a non-empty `type`
+plus the shared OKF surface — so the wiki bundle stays conformant and the
+strategy/thumbnail siblings can read it. The body holds the human-readable
+package; cross-references use standard markdown links, never `[[wikilinks]]`.
+
+```markdown
+---
+type: youtube-package
+title: Package — Learn Python in 2026 (beginner tutorial)
+description: Title set, description, tags, hashtags and chapters for the 12-minute beginner Python tutorial.
+tags: [youtube, packaging]
+timestamp: 2026-05-28T00:00:00Z
+---
+# Package — Learn Python in 2026 (beginner tutorial)
+
+## Titles (A/B set)
+- Learn Python in 2026: 12-Min Beginner Tutorial
+- Python in 12 Minutes (Total Beginner)
+- I Taught a Beginner Python in 12 Min
+
+## Description
+<above-fold line + body + links + hashtag line, per §1>
+
+## Tags
+python, learn python, python tutorial, python for beginners, …
+
+## Hashtags
+#Python #LearnToCode #ProgrammingForBeginners
+
+## Chapters
+00:00 Intro — what you'll build
+…
+```
+
+> The `scripts/verify.sh` linter runs on the package **draft** (labeled sections,
+> no frontmatter). The persisted wiki file adds the frontmatter above the same
+> body — do not feed the frontmatter'd wiki copy to the linter, since its `tags:`
+> frontmatter key would be read as the Tags section.

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,164 @@
+---
+name: youtube-strategy
+description: "Use when a YouTube channel needs a system-level decision — positioning and niche, upload cadence, how videos chain into playlists and series, end-screen routing, or a what-is-working review — read from and written back to the channel's own learning wiki rather than one video's choices. NOT generating next-video topics (that is `youtube-ideation`), NOT per-video titles or 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, write-adr]
+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** `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 `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 `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 `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
+---
+type: youtube-strategy-record
+title: Niche down to budget mechanical keyboards for programmers
+description: Reposition from broad tech reviews to budget mechanical keyboards for programmers; hold 2/wk cadence.
+tags: [youtube, strategy-decision, positioning]
+timestamp: 2026-06-02T00:00:00Z
+---
+# 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](./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
+```
+
+`docs/wiki/` is an OKF v0.1 bundle: every record carries a non-empty `type` (`youtube-strategy-record`) above the body, and cross-references use standard markdown links (never `[[wikilinks]]`). 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 docs/wiki/youtube/` after writing to confirm the records are structurally complete (date, `Decision:`, metric, and `type`). Full templates in `references/wiki-records.md`.
+
+## 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 `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 `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`.