@damiangilgonzalez/harness 1.3.7

package/skills/youtube-ideation/references/idea-ledger-and-loop.md

@@ -0,0 +1,89 @@
+# Idea ledger + hypothesis/outcome log — templates and a worked example
+
+Two artifacts, both Markdown, both in `docs/`. The ledger is rewritten each run (it is
+the current shortlist). The log is **append-only** — it is the audit trail and must never
+be overwritten.
+
+## Artifact 1 — the idea ledger
+
+Header records the baseline so "outlier signal" and every later hypothesis are anchored.
+
+```markdown
+# Idea ledger — <channel> — <YYYY-MM-DD>
+Baseline: <N> avg views (from <M> videos, computed YYYY-MM-DD via youtube-api log)
+
+| # | Idea (one sentence) | Fit | Demand | Outlier | Pkg | Ret | Orig | Money | /35 | Verdict | Evidence | AI-flag |
+|---|---------------------|-----|--------|---------|-----|-----|------|-------|-----|---------|----------|---------|
+```
+
+- Each dimension cell is an integer 1–5.
+- `/35` is the sum; `Verdict` is one of `produce` / `improve` / `gray` / `abandon` and must
+  match the band (30–35 produce, 24–29 improve, 18–23 gray, <18 abandon).
+- `Evidence` carries the outlier links + a search number — never blank for a non-zero demand
+  score.
+- `AI-flag` = `yes` if the idea leans on AI-generated media (disclosure-label risk), else `-`.
+
+## Artifact 2 — the append-only hypothesis/outcome log
+
+```markdown
+# Hypothesis/outcome log — <channel> (APPEND ONLY — never edit a past row)
+
+## <YYYY-MM-DD> — <idea>
+- predicted: <X>x baseline
+- why: <the mechanism — what makes this beat baseline>
+- judge-by: <metric> vs <baseline metric>
+- status: pending
+```
+
+After publish, **append** below the same entry (do not edit the lines above):
+
+```markdown
+### outcome <YYYY-MM-DD>
+- actual: <X>x baseline   (views <V> vs baseline <N>)
+- CTR: <c>% (channel median <m>%)   retention: <r>% (baseline <b>%)
+- verdict: validated | killed | inconclusive
+- lesson: <what this changes in the next scoring pass>
+```
+
+## Fully worked example
+
+### Ledger (run of 2026-06-02)
+
+```markdown
+# Idea ledger — buildwithcode — 2026-06-02
+Baseline: 6,250 avg views (from 18 videos, computed 2026-06-02 via youtube-api log)
+
+| # | Idea | Fit | Demand | Outlier | Pkg | Ret | Orig | Money | /35 | Verdict | Evidence | AI-flag |
+|---|------|-----|--------|---------|-----|-----|------|-------|-----|---------|----------|---------|
+| 1 | I rebuilt my SaaS the way senior devs do | 5 | 4 | 5 | 5 | 4 | 4 | 4 | 31 | produce | 6 outliers 3.4–7.1x; "rebuild" autocomplete + Trends 28d rising | - |
+| 2 | My honest thoughts on the new framework | 4 | 2 | 2 | 2 | 3 | 3 | 3 | 19 | gray | 1 outlier 2.1x; flat Trends | - |
+| 3 | AI wrote my entire backend — does it work | 4 | 3 | 4 | 4 | 3 | 3 | 2 | 23 | gray | 4 outliers 3.0–5.2x; AI media heavy | yes |
+```
+
+Idea 1 clears 30 → promote with a hypothesis. Ideas 2 and 3 sit in the gray band:
+re-angle, don't produce as-is. Idea 3 also carries an AI-flag (disclosure-label risk).
+
+### Log entry at promotion
+
+```markdown
+## 2026-06-02 — I rebuilt my SaaS the way senior devs do
+- predicted: 2.5x baseline
+- why: 6 niche outliers all open on the same "I did it wrong for years" stakes in 8s,
+  and we own a real refactor with before/after numbers none of them have.
+- judge-by: 28-day views vs trailing-10 average (6,250) AND CTR vs channel median (4.1%)
+- status: pending
+```
+
+### Outcome appended after publish
+
+```markdown
+### outcome 2026-07-05
+- actual: 3.1x baseline   (views 19,400 vs baseline 6,250)
+- CTR: 5.8% (channel median 4.1%)   retention: 47% (baseline 39%)
+- verdict: validated
+- lesson: the "I did it wrong for years" cold-open beat our usual intro on retention —
+  bump Retention-potential weight for ideas that can open on a personal-mistake stake.
+```
+
+That lesson is what makes the next run's scoring smarter than this one's. The original
+prediction lines are untouched — that is the whole point of append-only.

package/skills/youtube-ideation/references/research-and-signals.md

@@ -0,0 +1,92 @@
+# Research, outlier math, and demand signals (2026)
+
+All sources accessed 2026-06-02.
+
+## Outlier score — the math, worked
+
+```text
+outlier_multiple = video_views / channel_average_views
+```
+
+The multiple is a **performance multiplier against this channel's own average**, so it is
+fair across channel sizes — a raw view count is not.
+
+| Channel avg | Video views | Multiple | Read |
+| --- | --- | --- | --- |
+| 6,250 | 50,000 | **8.0x** | a genuine breakout on a small channel |
+| 1,800,000 | 500,000 | **0.3x** | a *miss* on a huge channel, despite the big absolute number |
+
+Pro reading of the ranges:
+
+- **3x or better = a real signal.** Worth mining for a reproducible trait.
+- **~2x = likely noise** — inside normal channel variance; don't bet on it alone.
+- **One outlier is an anecdote.** Collect **5–10** in the same niche and extract the
+  *shared* trait (the cold-open stakes, the title structure, the proof format) — that
+  shared trait is the bet, not the single video.
+
+Sources: OutlierKit — "What Is a YouTube Outlier Score? (Calculation, Ranges, Uses)" and
+"How to Find Viral Outlier Videos"; vidIQ Help Center — "Outliers".
+
+## The 6-step research-led pipeline (expanded)
+
+Brainstorm-first fails because it scores "outlier signal" on imagination. Run in order:
+
+1. **Analyze niche channels.** Pick channels adjacent to yours that are winning.
+2. **Find outlier videos.** Sort by *multiple*, not raw views. Keep ones at 3x+.
+3. **Study title/thumbnail patterns.** What do the 3x+ winners share? Name it.
+4. **Identify content gaps.** Demand the outliers proved, that nobody owns well — or that
+   you can own better with unique proof.
+5. **Check audience + trend signals.** (Sources table below.) Confirm live demand.
+6. **Generate original variations.** Your angle and your proof — never a re-shoot of an
+   outlier.
+
+> "More ideas do not grow a channel. Better decisions do." — OverseerOS, "Best YouTube
+> Video Idea Generator Tools in 2026" (published 2026-05-13, updated 2026-05-18).
+
+## Demand signals — free first, paid for real volume
+
+| Source | Tier | What it gives you |
+| --- | --- | --- |
+| YouTube Studio **Trends** tab | free | top searches for *your* audience + saved topics over the last 28 days |
+| **Google Trends** | free | direction + seasonality of a topic (relative, not absolute volume) |
+| YouTube **autocomplete** | free | the actual query phrasings real viewers type |
+| **OutlierKit** | paid | outlier discovery + keyword/search volume |
+| **Keywords Everywhere** | paid | search-volume numbers inline |
+| **vidIQ** | paid | volume + trending tab + ~50 "Daily Ideas"/day; weights vs channel |
+| **TubeBuddy** | paid | keyword score weighted against *your* channel's authority |
+| **Semrush** | paid | broader keyword volume + competition |
+| **1of10 / TubeLab** | paid | outlier discovery |
+
+Note: TubeBuddy and vidIQ also offer title/thumbnail A/B testing — that is a **packaging**
+job (`../youtube-packaging/SKILL.md`), not ideation. Use them here only for the demand
+signal.
+
+The three fast pre-tests every idea must pass before `produce`: (1) statable in one
+sentence; (2) serves the core audience **and** reaches new viewers; (3) search/trend demand
+exists and is recorded on the row.
+
+Sources: OverseerOS idea-generator guide; OutlierKit — "YouTube Keyword Research: Complete
+2026 Guide"; Semrush — "How to do YouTube keyword research: 2026 guide".
+
+## The closed loop
+
+The full cycle: validate idea → build hook → script → edit → publish → study the retention
+graph → **feed the lesson back into the next pick**. The back-half — writing the measured
+outcome back so the next scoring pass is smarter — is the part most creators skip, and the
+reason the hypothesis/outcome log is append-only and dated.
+
+Sources: OverseerOS idea-generator guide; OverseerOS — "Best YouTube Retention Tools in
+2026".
+
+## 2026 platform context that weights a bet
+
+- **Shorts-first storytelling is the dominant discovery force.** It lowers production
+  friction, tests messaging fast, and fits mobile attention — weight format reach in
+  scoring. Source: Dash Social / mean.ceo 2026 trend roundup.
+- **AI-content disclosure labels** are rolling out (voluntary or auto-applied). An idea that
+  leans on AI-generated media can be dampened by the label — flag it on the row. Source:
+  9to5Google — "AI-generated YouTube content to get 'more visible' disclosure label"
+  (2026-05-27).
+
+The durable format-mix / cadence call is **not** made here — it belongs to
+`../youtube-strategy/SKILL.md`. These notes only weight the individual bet.

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

@@ -0,0 +1,237 @@
+#!/usr/bin/env bash
+#
+# verify.sh — structural lint for the `youtube-ideation` idea ledger + outcome log.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Static checks over a produced idea ledger (Markdown). It validates the SHAPE of
+#   the decision, never whether the ideas are good. For each ledger found:
+#     1. Every scored idea row (a table row with seven 1-5 cells) has all 7 rubric
+#        dimensions filled 1-5 AND a /35 total that equals their sum.
+#     2. The /35 total matches its verdict band:
+#          >=30 produce | 24-29 improve | 18-23 gray | <18 abandon
+#        A mismatch (e.g. total 31 tagged "abandon") fails; the 18-23 gray band warns.
+#     3. Every "produce" idea has demand evidence on the row (non-empty Evidence).
+#     4. If a hypothesis/outcome log section is present, it is append-only-shaped:
+#        each dated bet is either "status: pending" OR carries actual + a verdict of
+#        validated|killed|inconclusive + a lesson. A bet that is neither fails.
+#
+#   A missing/empty target is a SKIP, never a failure. Pure text/awk, no deps.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh                      # scan ./ for *ledger*/*idea*.md
+#   ./verify.sh --path ledger.md     # check one ledger
+#   ./verify.sh --path docs/      # scan a directory
+#   ./verify.sh --strict             # treat warnings (gray-band rows) as failures
+#
+# EXIT CODES
+#   0  clean, empty target, or warnings only without --strict
+#   1  a real failure (bad row, band mismatch, broken hypothesis/outcome shape)
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays.
+
+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
+
+ok_count=0; skip_count=0; warn_count=0; fail_count=0
+
+usage() { sed -n '2,33p' "$0" | sed 's/^# \{0,1\}//'; }
+
+SCAN_PATH="."
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path)   SCAN_PATH="${2:?--path needs a value}"; shift 2 ;;
+    --strict) STRICT=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) printf '%sUnknown argument: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+  esac
+done
+
+summary() { printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"; }
+
+if [ ! -e "$SCAN_PATH" ]; then
+  printf '%s[skip]%s path not found: %s — nothing to check\n' "$YELLOW" "$NC" "$SCAN_PATH"
+  skip_count=1; summary; exit 0
+fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+if ! have awk; then
+  printf '%s[skip]%s awk not found — cannot parse ledger\n' "$YELLOW" "$NC"
+  skip_count=1; summary; exit 0
+fi
+
+# Collect candidate ledger files: prefer named ledger/idea files, else any .md.
+FILES=""
+if [ -f "$SCAN_PATH" ]; then
+  FILES="$SCAN_PATH"
+else
+  FILES="$(find "$SCAN_PATH" -type f -name '*.md' \( -iname '*ledger*' -o -iname '*idea*' \) 2>/dev/null || true)"
+  if [ -z "$FILES" ]; then
+    FILES="$(find "$SCAN_PATH" -type f -name '*.md' 2>/dev/null || true)"
+  fi
+fi
+
+if [ -z "$FILES" ]; then
+  printf '%s[skip]%s no idea ledger found under %s — nothing to check (clean)\n' "$YELLOW" "$NC" "$SCAN_PATH"
+  skip_count=1; summary; exit 0
+fi
+
+# check_one <file>: one awk pass emits "LEVEL message" lines; the shell tallies.
+check_one() {
+  f="$1"
+  [ -s "$f" ] || { printf 'SKIP empty file: %s\n' "$f"; return; }
+  printf 'HDR %s\n' "$f"
+
+  awk '
+    # Lowercase compare; BSD awk has no IGNORECASE.
+    {
+      line=$0
+      lc=tolower($0)
+
+      # ---- scored idea rows: a markdown table row with >=7 integer cells (1-5) ----
+      # Heuristic: pipe-delimited row, not the header/separator, that contains a
+      # verdict word AND a standalone /35-style total. We split on | and read cells.
+      # separator row = only pipes, dashes, colons and spaces (no letters/digits)
+      issep = (line ~ /^[ ]*\|[ |:-]*$/)
+      if (line ~ /\|/ && !issep && (lc ~ /produce|improve|abandon|gray|grey/)) {
+        n=split(line, c, "|")
+        ints=0; sum=0; total=""; verdict=""; firstint=""
+        for (i=1;i<=n;i++) {
+          cell=c[i]; gsub(/[ \t*]/,"",cell)
+          if (cell ~ /^[1-5]$/) { ints++; sum+=cell+0; if(firstint=="") firstint=cell+0 }
+          else if (cell ~ /^[0-9]+$/ && (cell+0)>=0 && (cell+0)<=35) { total=cell+0 }
+          lcell=tolower(cell)
+          if (lcell ~ /^produce$/)  verdict="produce"
+          if (lcell ~ /^improve$/)  verdict="improve"
+          if (lcell ~ /^abandon$/)  verdict="abandon"
+          if (lcell ~ /^gr[ae]y$/)  verdict="gray"
+        }
+        if (verdict=="") next   # not actually an idea row
+        rows++
+
+        # A leading "#" index column is itself a 1-5 integer; if we counted 8, the
+        # first is the row index, not a rubric dimension — drop it from the sum.
+        if (ints == 8) { ints=7; sum=sum-firstint }
+
+        if (ints < 7) {
+          print "FAIL row " rows ": only " ints " of 7 rubric dimensions are integers 1-5"
+          next
+        }
+        if (ints > 7) {
+          print "FAIL row " rows ": " ints " integer cells 1-5 — expected exactly 7 rubric dimensions"
+          next
+        }
+        if (total=="") {
+          print "FAIL row " rows ": no /35 total cell found"
+          next
+        }
+        if (total != sum) {
+          print "FAIL row " rows ": total " total " != sum of dimensions " sum
+        } else {
+          print "OK row " rows ": 7 dims, total " total " matches sum"
+        }
+
+        # band check against verdict
+        band=""
+        if (total>=30) band="produce"
+        else if (total>=24) band="improve"
+        else if (total>=18) band="gray"
+        else band="abandon"
+        if (band != verdict)
+          print "FAIL row " rows ": total " total " is band \"" band "\" but verdict is \"" verdict "\""
+        else if (verdict=="gray")
+          print "WARN row " rows ": gray band (" total ") — re-angle or shelve, do not produce as-is"
+        else
+          print "OK row " rows ": verdict \"" verdict "\" matches band"
+
+        # produce rows need demand evidence somewhere on the row
+        if (verdict=="produce") {
+          producerows++
+          # crude evidence test: an outlier multiple like 3.4x or a digit-bearing note
+          if (lc ~ /[0-9]+(\.[0-9]+)?x/ || lc ~ /outlier|trends|autocomplete|search/) {
+            # ok
+          } else {
+            print "WARN row " rows ": produce idea has no visible demand evidence (outlier/search) on its row"
+          }
+        }
+      }
+
+      # ---- hypothesis/outcome log shape ----
+      # A dated bet header: "## YYYY-MM-DD — <idea>"
+      if (line ~ /^#+[ ]+(19|20)[0-9][0-9]-[0-1][0-9]-[0-3][0-9]/) {
+        # close out the previous bet before opening a new one
+        if (inbet) closebet()
+        inbet=1; bettitle=$0; haspending=0; hasactual=0; hasverdict=0; haslesson=0
+        bets++
+      }
+      else if (inbet) {
+        if (lc ~ /status:[ ]*pending/) haspending=1
+        if (lc ~ /actual:/) hasactual=1
+        if (lc ~ /verdict:[ ]*(validated|killed|inconclusive)/) hasverdict=1
+        if (lc ~ /lesson:/) haslesson=1
+        # a non-date top-level heading also closes the bet
+        if (line ~ /^#[ ]/ && line !~ /(19|20)[0-9][0-9]-/) { closebet(); inbet=0 }
+      }
+    }
+    function closebet() {
+      if (haspending) { print "OK bet pending: " substr(bettitle,1,60); return }
+      if (hasactual && hasverdict && haslesson) { print "OK bet closed (actual+verdict+lesson): " substr(bettitle,1,60); return }
+      m=""
+      if (!hasactual)  m=m" actual"
+      if (!hasverdict) m=m" verdict(validated|killed|inconclusive)"
+      if (!haslesson)  m=m" lesson"
+      print "FAIL bet neither pending nor complete — missing:" m " :: " substr(bettitle,1,60)
+    }
+    END {
+      if (inbet) closebet()
+      if (rows==0) print "WARN no scored idea rows detected (is this an idea ledger?)"
+      if (rows>0)  print "OK " rows " scored idea row(s) parsed; " producerows " promoted to produce"
+      if (bets>0)  print "OK " bets " hypothesis/outcome bet(s) parsed"
+    }
+  ' "$f" 2>/dev/null
+}
+
+printf 'Checking idea ledgers under: %s\n\n' "$SCAN_PATH"
+printf '%s\n' "$FILES" | while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  check_one "$f"
+done > "/tmp/ytid_verify.$$" 2>&1 || true
+
+# Render with colored tags.
+while IFS= read -r line; do
+  case "$line" in
+    HDR*)  printf '%s—— %s%s\n' "$YELLOW" "${line#HDR }" "$NC" ;;
+    FAIL*) printf '%s[fail]%s %s\n' "$RED"    "$NC" "${line#FAIL }" ;;
+    WARN*) printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "${line#WARN }" ;;
+    OK*)   printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "${line#OK }" ;;
+    SKIP*) printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "${line#SKIP }" ;;
+    *)     printf '%s\n' "$line" ;;
+  esac
+done < "/tmp/ytid_verify.$$"
+
+tally() { { grep -c "$1" "/tmp/ytid_verify.$$" 2>/dev/null || true; } | tr -dc '0-9'; }
+fail_count=$(tally '^FAIL'); fail_count=${fail_count:-0}
+warn_count=$(tally '^WARN'); warn_count=${warn_count:-0}
+ok_count=$(tally '^OK');     ok_count=${ok_count:-0}
+skip_count=$(tally '^SKIP'); skip_count=${skip_count:-0}
+rm -f "/tmp/ytid_verify.$$" 2>/dev/null || true
+
+summary
+
+cat <<'EOF'
+
+Note: this gate proves the ledger is SHAPED RIGHT (7 dims sum to a /35 that matches its
+verdict band, produce rows carry demand evidence, and every logged bet is pending or fully
+graded). It does NOT judge whether the ideas are good — that is the capability eval's job.
+Re-run with --strict to gate CI on a clean pass (gray-band rows then fail).
+EOF
+
+if [ "$fail_count" -gt 0 ]; then exit 1; fi
+if [ "$STRICT" -eq 1 ] && [ "$warn_count" -gt 0 ]; then exit 1; fi
+exit 0

package/skills/youtube-packaging/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: youtube-packaging
+description: "Use when writing or fixing the text that ships with a YouTube upload — title, description, tags, hashtags and chapters — when click-through is weak and the words are the suspect, or when closing the loop on what last performed. NOT designing the thumbnail image (that is `youtube-thumbnails`), NOT inventing the idea or angle (that is `youtube-ideation`), NOT the channel growth plan (that is `youtube-strategy`), NOT pushing the fields via the Data API (that is `youtube-api`)."
+tags: [youtube, video-seo, titles, descriptions, chapters]
+recommends: [youtube-thumbnails, youtube-ideation, youtube-strategy, youtube-api, video-shorts, seo-geo, social-publisher]
+profiles: []
+origin: risco
+---
+
+# YouTube packaging
+
+You write the text that ships with the upload — title, description, tags,
+hashtags, chapters — and you optimize it against what actually performed, not
+against a hunch. A strong video dies on a weak package. You are not the picture,
+not the idea, not the channel plan, and not the API that uploads any of it.
+
+## What you produce
+
+Five concrete text artifacts plus one feedback entry, every time:
+
+1. **A title SET** — 2-3 titles, never one. (Why: YouTube tests titles, so you
+   ship a hypothesis to measure, not a guess to defend.)
+2. **A description block** — above-the-fold line + body + links + hashtag line.
+3. **A tag list** — 5-8 tags, first = exact target phrase.
+4. **A hashtag line** — 3-5 hashtags inside the description.
+5. **A chapter list** — timestamps that obey four exact rules.
+6. **A feedback-log update** in `docs` — what you tried, what won, the numbers.
+
+**Co-ownership note, up front:** YouTube tests the title+thumbnail pair as ONE
+unit. The *title hypothesis to test* is co-owned with
+[youtube-thumbnails](../youtube-thumbnails/SKILL.md); the **wordsmithing of the
+title and all other metadata lives here**. Draw the image there, write the words
+here.
+
+## Ground first (STOP gate)
+
+Before you write a single title, read the channel. Skipping this is how you
+produce generic copy in someone else's voice.
+
+- Read `docs/wiki/youtube/` for the channel's **brand voice**, prior packages,
+  and the **performance feedback log** (winners and losers from past tests).
+- Pull the decided **idea/angle** from [youtube-ideation](../youtube-ideation/SKILL.md)
+  output if it exists.
+- **No decided topic/angle yet? Route OUT to `youtube-ideation`. Never invent the
+  topic here.** (Why: packaging a video with no settled angle is guessing at the
+  hook, the keyword, and the audience all at once.)
+
+Persist what you write under `docs/wiki/youtube/` (the package) and raw test
+results under `docs/raw/youtube/`. `docs/wiki/` is an **OKF v0.1** bundle:
+every package or log file persisted there carries YAML frontmatter with a
+non-empty `type` (`youtube-package`) plus the OKF surface (`title`, `description`,
+`tags`, `timestamp`) shared with the strategy/thumbnail/api siblings, and all
+cross-references use standard markdown links — never `[[wikilinks]]`. The OKF
+frontmatter shape for the persisted package and log is in
+[references/description-and-chapters.md](references/description-and-chapters.md).
+
+## The title
+
+The single highest-leverage field. Rules, each with one reason:
+
+- **Hard limit 100 chars; visible budget ~60.** Titles truncate around 60-70 chars
+  on desktop and ~50-60 on mobile. The most compelling words + the primary keyword
+  must land in the first ~60 chars / first 5 words — everything after that may
+  never be seen.
+- **Front-load the keyword and the hook.** Shape: Hook + Keyword + Benefit inside
+  the first 60 chars. Channels report 15-25% higher CTR for titles kept in the
+  60-70 char range.
+- **Use numbers and specificity.** Titles with numbers report ~20-30% higher CTR;
+  a parenthetical qualifier (year, difficulty, format) adds precision without
+  burning the budget.
+- **Emit a SET of 2-3 titles framed as an A/B hypothesis** — never ship one.
+  Test & Compare auto-applies the variant with the highest *watched time per
+  impression*, **not raw CTR**. (Why this matters: a clickbait title that wins the
+  click but loses the viewer will LOSE the test. Write for the click AND the stay.)
+
+Bad -> Good (front-load, cut the filler, add specificity):
+
+```text
+Bad   In this video I'll show you how to learn Python
+Good  Learn Python in 2026: 12-Minute Beginner Tutorial
+
+Bad   My honest thoughts after using the new framework for a while
+Good  I Shipped 3 Apps on This Framework — Here's the Verdict
+
+Bad   Tips for better sleep that actually work I promise
+Good  7 Sleep Fixes That Doubled My Deep Sleep (No Pills)
+```
+
+Decide the title shape by how the video will be found — this is a real branch:
+
+| Discovery mode | Title shape | Example |
+|---|---|---|
+| Search-led (tutorial, how-to, "best X") | Keyword first, literal, benefit-clear | `Fix Slow Next.js Builds: 5 Proven Steps` |
+| Browse-led (commentary, vlog, story) | Curiosity/stakes first, keyword secondary | `I Rebuilt My App and Regretted Everything` |
+
+Search-led titles answer a query; browse-led titles win a scroll. Most videos
+lean one way — pick it deliberately, then write the set inside that shape.
+
+## The description
+
+Only the first ~125 chars are above the fold — the rest hides behind "Show more"
+and is unseen by most viewers.
+
+- **First 1-2 lines (~100-150 chars): primary keyword + who-it's-for.** This is
+  the one part that shows in search and the watch page before the fold. Spend it on
+  substance, not "Welcome to my channel."
+- **Body: ~200-350 words of natural, keyword-rich prose. No stuffing.** Write for a
+  human; weave the keyword and 1-2 variants in naturally. Keyword lists read as
+  spam and help nothing.
+- **Links block** (resources, socials, gear) then the **3-5 hashtag line**.
+- **One clear CTA** (subscribe / next video / comment prompt).
+
+The full template + a fully filled example live in
+[references/description-and-chapters.md](references/description-and-chapters.md).
+
+## Chapters
+
+Chapters obey **four exact rules. Break any one and YouTube ignores ALL chapters.**
+Run this checklist on every chapter block:
+
+- [ ] **At least 3 timestamps.**
+- [ ] **The first timestamp is `00:00`.** (This is the silent killer — omit `0:00`
+      and every later timestamp is discarded.)
+- [ ] **Each chapter is at least 10 seconds long.**
+- [ ] **Timestamps are in 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
+```
+
+Why bother: chapters lift watch time and give search a jump-to target. The four
+failure cases worked through line by line are in
+[references/description-and-chapters.md](references/description-and-chapters.md).
+
+## Tags & hashtags
+
+Different fields, different rules — and one of them barely matters:
+
+| Field | Count | Placement | Weight |
+|---|---|---|---|
+| Tags | 5-8 (up to 10-20), ~500-char budget | the Tags input box | **minimal ranking impact**; first tag weighted slightly more |
+| Hashtags | 3-5 relevant; **max 15** | inside the description | first 3 render above the title; **>15 = ALL stripped** |
+
+- **Tags: make the first tag the exact target phrase; do not over-invest.** YouTube
+  calls tags' discovery role "minimal" — they mainly fix misspellings and
+  disambiguate. Spend 2 minutes here, not 20.
+- **Hashtags: pick 3-5 relevant ones; never exceed 15.** Only the first three show
+  above the title, so order them best-first. Exceed 15 and YouTube strips every
+  hashtag — you get zero, not 15.
+
+## The learning loop
+
+This is what makes the skill *learn* instead of guess. Because Test & Compare
+measures variant performance directly, every package is logged and graded.
+
+**Read before you write.** Open the feedback log in `docs/wiki/youtube/` and
+carry forward what won as priors: if numeric titles beat curiosity titles 3 tests
+running on this channel, the new set leans numeric. If a hashtag set tanked, drop
+it.
+
+**Append after you test.** One row per test, into `docs/wiki/youtube/packaging-log.md`
+(OKF v0.1: file-level `type: youtube-package` frontmatter at the top, the table
+below it, newest rows appended, past rows immutable):
+
+```text
+| date | video | title set tried | winner | CTR | impressions | avg view duration | note |
+```
+
+The cycle: read winners/losers -> write the new package as informed priors ->
+ship the A/B set -> when Test & Compare resolves (~2 weeks), append the result ->
+the next package is a little less of a guess. The full schema with a filled row is
+in [references/description-and-chapters.md](references/description-and-chapters.md).
+
+**Grade by watched-time-per-impression, not raw CTR.** A title can win clicks and
+still lose the test by losing viewers. Log both so the lesson is honest.
+
+## Handoffs
+
+Stay inside the text fields. Everything else routes out:
+
+| Ask | Owner |
+|---|---|
+| Design/generate the thumbnail image | [youtube-thumbnails](../youtube-thumbnails/SKILL.md) |
+| Come up with the idea / topic / angle | [youtube-ideation](../youtube-ideation/SKILL.md) |
+| Channel growth plan, niche, cadence | [youtube-strategy](../youtube-strategy/SKILL.md) |
+| Upload/update metadata via the Data API | [youtube-api](../youtube-api/SKILL.md) |
+| Cross-platform short caption/hook (TikTok/Reels) | [video-shorts](../video-shorts/SKILL.md) |
+| Keyword research for web/AI search (not YouTube) | [seo-geo](../seo-geo/SKILL.md) |
+| Schedule/publish the post to socials | [social-publisher](../social-publisher/SKILL.md) |
+
+The tell: if the ask is **the text fields of the YouTube upload**, it is here. The
+picture, the idea, the channel plan, the API call — each is a sibling.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| "In this video I'll show you…" opener | Burns the visible ~60-char budget on filler | Front-load keyword + hook in the first 5 words |
+| Shipping ONE title | No hypothesis, nothing to learn | Always a SET of 2-3 for Test & Compare |
+| Keyword-stuffing the description | Reads as spam, helps nothing | ~200-350 words of natural prose, keyword woven in |
+| Clickbait the video can't cash | Wins the click, loses the viewer, LOSES the A/B | Promise what the video delivers |
+| Chapters with no `00:00` / <3 / <10s / out of order | YouTube silently ignores ALL chapters | Run the four-rule checklist |
+| >15 hashtags | YouTube strips every one — you get zero | 3-5 relevant, best three first |
+| Obsessing over tags | They have minimal ranking impact | 5-8, first = target phrase, move on |
+| Ignoring the feedback log | Every package stays a fresh guess | Read prior winners, carry them as priors |
+| Optimizing CTR while view duration tanks | Test & Compare scores watched-time-per-impression | Log both; write for click AND stay |
+
+## Verify
+
+Run [scripts/verify.sh](scripts/verify.sh) on an emitted package file (the title
+set, description, tags, hashtags, and chapters as one structured block). It is
+read-only and lints the mechanical constraints: ≥2 titles, each ≤100 chars;
+above-the-fold first line present and not over-long; ≥3 chapters with first `0:00`,
+ascending, ≥10s gaps; 1-15 hashtags; tags within the ~500-char budget. A clean or
+empty file exits 0.
+
+## See also
+
+- [youtube-thumbnails](../youtube-thumbnails/SKILL.md) — the image the title sits on; the pair is tested together.
+- [youtube-ideation](../youtube-ideation/SKILL.md) — the idea/angle you package here.
+- [youtube-strategy](../youtube-strategy/SKILL.md) — channel positioning, niche, cadence.
+- [youtube-api](../youtube-api/SKILL.md) — programmatic upload/update of these fields.

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

@@ -0,0 +1,16 @@
+# Evals — youtube-packaging
+
+These cases are read by the repo's skill-eval harness. `should_trigger` and
+`should_not_trigger` check routing precision: each prompt is matched against this
+skill's description versus its siblings, and the `route_to` ids
+(`youtube-thumbnails`, `youtube-ideation`, `youtube-api`, `youtube-strategy`,
+`seo-geo`) must win their own cases — the thumbnail, the idea, the API call, the
+channel plan, and non-YouTube SEO all belong elsewhere. The `capability` case is
+scored by a judge against its `must_include` rubric: it checks that a generated
+package grounds in `docs` first, emits a 2-3 title A/B set within the char
+budget, an above-the-fold description line plus a natural ~200-350 word body and a
+3-5 hashtag line, chapters obeying all four rules, 5-8 tags with the right first
+tag, a feedback-log update, correct handoffs, and the watched-time-per-impression
+framing. Run them through the repo's eval runner; no live YouTube account, upload,
+or network access is required — the capability run is a dry-run producing text
+artifacts and a feedback-log row only.