@damiangilgonzalez/harness 1.3.7

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 `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 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. 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 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 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,119 @@
+# 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.
+
+`docs/wiki/` is an **OKF v0.1** bundle, so every `.md` record this skill writes carries YAML frontmatter with a non-empty `type` (`youtube-strategy-record`) plus the OKF surface (`title`, `description`, `tags`, `timestamp`). These are shared, identically, across all four youtube skills. The strategy-specific body fields the loop and `verify.sh` rely on (`Decision:`, `Bets on metric:`, the date) stay in the body exactly as before — the frontmatter is purely additive. All cross-references use standard markdown links (`[text](./file.md)`), never `[[wikilinks]]`.
+
+## File layout under `docs/wiki/youtube/`
+
+```text
+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 `docs/wiki/youtube/` does not exist, create it and a positioning stub before deciding anything:
+
+```bash
+mkdir -p docs/wiki/youtube/decisions
+```
+
+`positioning.md` stub:
+
+```markdown
+---
+type: youtube-strategy-record
+title: Channel positioning
+description: The channel's current niche, who-it's-for, and three-factor rationale.
+tags: [youtube, positioning]
+timestamp: 2026-06-02T00:00:00Z
+---
+# 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 the frontmatter (`type` + OKF surface) **and** these body fields. The metric line is mandatory — a decision with no metric is an opinion, not a checkable bet. The body fields (`Decision:`, `Bets on metric:`, the date) are what `verify.sh` lints, so keep them verbatim; the frontmatter sits above them.
+
+```markdown
+---
+type: youtube-strategy-record
+title: <one-line decision title>
+description: <one-sentence summary of the decision and what it bets on>
+tags: [youtube, strategy-decision]
+timestamp: <YYYY-MM-DDTHH:MM:SSZ>
+---
+# <YYYY-MM-DD> — <one-line decision title>
+- Context read: <what the wiki/data said that drove this; cite files with markdown links>
+- 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
+---
+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, holding 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"; 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
+
+`what-worked.md` carries the file-level frontmatter once at the top; below it, **append one entry per observed win or loss** (append-only, ISO 8601 dates, past entries immutable), tied to a real asset so future sessions can pattern-match. Refresh `timestamp` when you append.
+
+```markdown
+---
+type: youtube-strategy-record
+title: What worked — wins and losses log
+description: Running log of channel wins/losses tied to specific videos and playlists.
+tags: [youtube, what-worked]
+timestamp: 2026-05-20T00:00:00Z
+---
+# What worked
+
+## <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 entry (appended under the frontmatter + heading):
+
+```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 docs/wiki/youtube/` is a read-only structural lint, no network:
+
+1. The target `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).
+4. Each decision record carries a non-empty `type:` frontmatter field (the OKF v0.1 conformance check). A record with no `type` is a hard failure.
+
+A record missing the metric or `type` 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. The `type` check is additive: it does not touch the existing date/`Decision:`/metric checks.

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

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+#
+# verify.sh — structural lint for a youtube-strategy wiki under docs/wiki/youtube/.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Static, network-free checks on the decision records the skill writes back.
+#     1. The target directory exists.
+#     2. At least one decision record is present: a file under decisions/*.md
+#        OR a running decisions.md log at the target root.
+#     3. Each decision record carries the three required signals:
+#          - a date            (a YYYY-MM-DD anywhere in the file)
+#          - a Decision: line   (the concrete choice)
+#          - a named metric/bet (a "Bets on metric:" / "metric" / "bet" field)
+#        A record missing the metric/bet field is a HARD FAILURE — a decision with
+#        no metric is an opinion, not a checkable bet.
+#     4. Each decision record carries a non-empty `type:` frontmatter field
+#        (OKF v0.1 conformance). A record with no `type` is a HARD FAILURE.
+#
+#   Missing date or Decision line is also a hard failure. A missing/empty target
+#   (a fresh channel with no wiki yet) is reported and exits 0 — no false failure.
+#   Pure bash + grep, no dependencies. It is a lint, not a strategy oracle.
+#
+# HOW TO RUN
+#   ./verify.sh docs/wiki/youtube/    # lint a channel's strategy wiki
+#   ./verify.sh                          # no target -> nothing to check, exit 0
+#
+# EXIT CODES
+#   0  clean, or nothing to check
+#   1  a hard structural failure
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2.
+
+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; warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; ok_count=$((ok_count + 1)); }
+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,34p' "$0" | sed 's/^# \{0,1\}//'; }
+
+summary_exit() {
+  printf '\nok=%d warn=%d fail=%d\n' "$ok_count" "$warn_count" "$fail_count"
+  [ "$fail_count" -gt 0 ] && exit 1
+  exit 0
+}
+
+# --- arg parse --------------------------------------------------------------
+TARGET=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) usage; exit 0 ;;
+    -*) printf 'unknown flag: %s\n' "$1" >&2; usage >&2; exit 2 ;;
+    *) TARGET="$1"; shift ;;
+  esac
+done
+
+# No target, or missing dir -> nothing to check, clean exit (no false fail).
+if [ -z "$TARGET" ]; then
+  ok "no wiki path given — nothing to lint"
+  summary_exit
+fi
+if [ ! -d "$TARGET" ]; then
+  warn "directory not found: $TARGET — nothing to lint (fresh channel?)"
+  summary_exit
+fi
+ok "wiki directory exists: $TARGET"
+
+# --- collect decision records ----------------------------------------------
+# Per-decision files under decisions/, plus an optional running decisions.md log.
+RECORDS=""
+if [ -d "$TARGET/decisions" ]; then
+  for f in "$TARGET"/decisions/*.md; do
+    [ -f "$f" ] && RECORDS="$RECORDS$f
+"
+  done
+fi
+[ -f "$TARGET/decisions.md" ] && RECORDS="$RECORDS$TARGET/decisions.md
+"
+
+# Trim trailing newline / handle empty.
+RECORDS="$(printf '%s' "$RECORDS" | sed '/^$/d')"
+
+if [ -z "$RECORDS" ]; then
+  warn "no decision records yet (decisions/*.md or decisions.md) — nothing to lint"
+  summary_exit
+fi
+
+# --- per-record structural checks ------------------------------------------
+DATE_RE='[0-9]{4}-[0-9]{2}-[0-9]{2}'
+
+while IFS= read -r rec; do
+  [ -z "$rec" ] && continue
+  if [ ! -s "$rec" ]; then
+    fail "$rec: empty record"
+    continue
+  fi
+
+  miss=""
+  grep -Eq "$DATE_RE"                    "$rec" || miss="$miss date"
+  grep -Eiq '^[[:space:]-]*Decision:'    "$rec" || miss="$miss decision-line"
+  grep -Eiq '(bets on metric:|metric|bet:)' "$rec" || miss="$miss metric/bet"
+  # OKF v0.1: a non-empty `type:` frontmatter field is required.
+  grep -Eiq '^[[:space:]]*type:[[:space:]]*[^[:space:]]' "$rec" || miss="$miss type"
+
+  if [ -n "$miss" ]; then
+    fail "$rec: missing required field(s):$miss"
+  else
+    ok "$rec: date + decision + metric present"
+  fi
+done <<EOF
+$RECORDS
+EOF
+
+summary_exit

package/skills/youtube-thumbnails/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: youtube-thumbnails
+description: "Use when designing or fixing a YouTube thumbnail, making variants for an A/B test, or working out which thumbnail style wins on a channel — including the trap where CTR looks fine but the test keeps selecting the duller image on watch-time share. NOT pairing the title with the thumbnail as one click-promise (that is `youtube-packaging`), NOT channel positioning or niche (that is `youtube-strategy`), NOT setting a thumbnail through the Data API (that is `youtube-api`)."
+tags: [youtube, thumbnails, ctr, ab-testing, design]
+recommends: [youtube-packaging, youtube-strategy, ab-testing, design]
+profiles: []
+origin: risco
+---
+
+# YouTube thumbnails
+
+Design thumbnails that survive the mobile feed, test them so the winner is a
+*lesson* and not a coin flip, and write every outcome back to the channel's wiki
+so the next thumbnail is evidence-led. A thumbnail you cannot learn from is half
+wasted.
+
+## The loop
+
+This skill runs a closed loop, not a one-off design pass:
+
+1. **Design** 2-3 candidate concepts that differ on exactly ONE testable axis.
+2. **Test** them in YouTube Studio "Test & Compare".
+3. **Log** the outcome to `docs/wiki/youtube/thumbnail-experiments.md`.
+4. **Learn**: mine the log into `thumbnail-patterns.md` (what wins on THIS
+   channel) and let that pick the next concept.
+
+The reason for the discipline: Test & Compare hands you a winner, never a reason.
+One varied axis per round is what turns a winner into a transferable rule.
+
+## Hard constraints
+
+These are objective and machine-checkable. `scripts/verify.sh` enforces the image
+ones; the rest are your job. Source facts: socialrails.com / thumbnailtest.com
+specs, accessed 2026-06-02.
+
+| Constraint | Value | Why |
+|---|---|---|
+| Resolution | 1280x720 px | YouTube's recommended size; anything smaller upscales soft |
+| Aspect ratio | 16:9 | The only ratio that fills the player and feed cleanly |
+| Min width | 640 px | Below this YouTube may reject the upload |
+| File size | under 2 MB | Hard cap for standard video (10 MB only for podcast thumbnails) |
+| Format | JPG or PNG | Also accepts GIF/BMP, but ship JPG/PNG |
+| Legibility | reads at 320x180 | Most discovery is the mobile feed at ~that scale — the "squint test" |
+| Safe zone | clear bottom-right | The duration stamp overlays that corner — no critical text/face/logo there |
+
+The squint test: shrink the image to 320x180 (or step back two meters from the
+screen). If the subject and any text are not instantly readable, it fails — design
+for the feed, not for the editor canvas. See
+`references/composition-and-specs.md` for the contrast math and export workflow.
+
+## Composition rules
+
+Each rule, one reason. Concrete beats abstract.
+
+- **One dominant focal point.** The eye must land in under a second; a thumbnail
+  with two competing subjects reads as none at 320x180.
+- **A face with one strong emotion** when the video allows it. Faces with clear
+  emotion lift CTR roughly 20-30%, and custom thumbnails run ~60-70% higher CTR
+  than auto-generated frames. One emotion, not a neutral stare.
+- **Subject ~30% brighter or darker than its background.** Separation is what
+  makes the subject pop in a scroll; a subject the same luminance as the bg
+  vanishes. Add a subtle outline or glow if the background is busy.
+- **2-3 bold colors, complementary.** More than three and the image turns to mud
+  at feed scale. Target a text/background contrast ratio of about 4.5:1 (a
+  usability heuristic, not a YouTube rule).
+- **Kill motion blur and clutter.** Anything that softens or crowds the frame dies
+  first when the image shrinks.
+
+## Text rules
+
+- **3-4 words maximum, maximum weight.** Heavy bold sans, large enough to read at
+  320x180. If it needs a second line of small type, cut it.
+- **Never in the bottom-right.** That is the duration-stamp safe zone.
+- **The thumbnail text must NOT just repeat the title.** They are two surfaces of
+  one promise, so make them add up instead of echo.
+
+Bad -> Good (text that wastes the surface):
+
+```text
+Bad   title: "I built a PC in 24 hours"   thumb text: "BUILT A PC IN 24H"
+Good  title: "I built a PC in 24 hours"   thumb text: "$200 BUDGET?!"
+```
+
+The Bad version spends both surfaces on the same words. The Good version lets the
+thumbnail carry the stakes the title leaves implicit. The *full* title<->thumbnail
+promise pairing — which surface owns which half of the hook — belongs to
+[youtube-packaging](../youtube-packaging/SKILL.md). Here, just don't duplicate.
+
+## Variant design for the A/B test
+
+This is where the flow branches, so decide deliberately.
+
+**Vary exactly ONE axis per variant set.** Change face vs object AND text AND
+color at once and a winning variant teaches you nothing — you cannot attribute the
+lift. Pick one axis from the menu and hold everything else constant.
+
+| Axis | Variant A | Variant B | What a win tells you |
+|---|---|---|---|
+| Subject | human face | the object/result | does your audience click people or things |
+| Expression | shock | calm/confident | which emotion this niche rewards |
+| Text | text present | no text | whether words help or clutter here |
+| Color | warm dominant | cool dominant | the channel's palette pull |
+| Layout | subject left | subject right | reading-order fit |
+| Zoom | tight crop | wide context | intimacy vs setting |
+
+Two variants is enough to isolate one axis cleanly; use the third slot only when a
+third level of the SAME axis is genuinely informative.
+
+## Test & Compare procedure
+
+YouTube's native A/B tool (broad rollout 2025). In Studio: open the video ->
+Thumbnail -> "Test & Compare" -> add variants.
+
+- **Up to 3 thumbnails** (and/or titles) per video.
+- **Winner is chosen by watch-time share, NOT raw CTR.** This is the trap that
+  breaks intuition: a punchy over-promising thumbnail can win the click and still
+  *lose* the test because the viewers it lured bounce, dragging watch time down.
+- **Runs up to ~2 weeks**, then YouTube auto-promotes the winner.
+- Let it reach significance — don't call it after two days of noise.
+
+The over-promise trap is the seam to [youtube-packaging](../youtube-packaging/SKILL.md):
+if your tests keep crowning the "boring" variant, the flashy one is writing a check
+the video doesn't cash. That is a promise problem, not an image problem.
+
+## The feedback loop (wiki)
+
+Every test result goes to the channel wiki. Exact path:
+`docs/wiki/youtube/`. `docs/wiki/` is an **OKF v0.1** bundle: both files
+below carry file-level frontmatter with a non-empty `type` (`thumbnail-experiment`)
+plus the OKF surface (`title`, `description`, `tags`, `timestamp`) shared with the
+api/strategy/packaging siblings, and cross-references use standard markdown links,
+never `[[wikilinks]]`.
+
+**Log file** — `thumbnail-experiments.md`, frontmatter at the top then one row per
+test (append-only, ISO 8601 dates, past rows immutable):
+
+```text
+| date | video | variants | axis tested | winner | CTR | watch-time share | note |
+```
+
+**Derived file** — `thumbnail-patterns.md`, frontmatter at the top then a running
+table of what wins on THIS channel (e.g. "faces beat objects 4/5 tests", "no-text
+wins on tutorials"). You update this after each logged test.
+
+**Next-concept rule:** the next thumbnail keeps the winning level of every axis
+already settled by the log, and tests the next unsettled axis. You only re-test a
+settled axis when the channel's content or audience visibly shifts.
+
+**Caveat:** on a small channel a single test is noise. Treat a pattern as real only
+after it holds across ~3+ tests or a clear, repeated margin. Full schema, filled
+example rows, and the pattern-mining heuristic live in
+`references/experiment-log-format.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| Tiny or thin text | Illegible at 320x180 feed scale | 3-4 words, heavy bold, squint-tested |
+| 5+ colors | Muddies into noise when shrunk | 2-3 complementary bold colors |
+| Clipart / stock faces | No emotion, no trust, reads as spam | Real face, one strong emotion |
+| Thumb text == title text | Wastes both surfaces of the promise | Thumb adds the stake the title omits |
+| Varying 3 axes per test | Winner is uninterpretable | One axis per variant set |
+| Trusting one test on a small channel | That's noise, not signal | Wait for ~3+ tests / repeated margin |
+| Designing in the full editor only | Looks great at 1280, dies in the feed | Check the 320x180 squint view |
+| Subject/logo in bottom-right | Duration stamp covers it | Keep that corner clear |
+| Chasing CTR while watch time tanks | Test & Compare scores watch-time share | Fix the over-promise (see youtube-packaging) |
+
+## Pre-publish checklist
+
+- [ ] Exactly 1280x720, 16:9, under 2MB, JPG or PNG (run `scripts/verify.sh`)
+- [ ] Passes the 320x180 squint test
+- [ ] Bottom-right corner clear of text/face/logo
+- [ ] Single dominant focal point; subject ~30% contrast vs background
+- [ ] 3-4 words max, heavy weight; text not duplicating the title
+- [ ] 2-3 colors only
+- [ ] Variant set differs on exactly ONE named axis
+- [ ] Test & Compare configured (<=3 variants, watch-time-share, ~2-week window)
+- [ ] Log row staged for `docs/wiki/youtube/thumbnail-experiments.md`
+
+## See also
+
+- [youtube-packaging](../youtube-packaging/SKILL.md) — the title<->thumbnail promise pair and hook framing.
+- [youtube-strategy](../youtube-strategy/SKILL.md) — channel positioning, niche, cadence.
+- [ab-testing](../ab-testing/SKILL.md) — rigorous experiment design on non-YouTube surfaces.
+- [design](../design/SKILL.md) — general visual systems and composition theory.

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

@@ -0,0 +1,11 @@
+# Evals — youtube-thumbnails
+
+These cases are LLM-graded against the rubric in `cases.yaml`, run through the
+repo's standard eval runner. `should_trigger` and `should_not_trigger` check
+routing — does the skill fire on real thumbnail/A-B work and stay quiet when the
+request belongs to a sibling (packaging, strategy, ideation, the API, ab-testing,
+or brand-identity)? `capability` checks the end-to-end behavior on the PC-build
+scenario: one-axis variants, the hard image constraints, correct Test & Compare
+setup (watch-time-share, not CTR), and a logged wiki row with the next-concept
+rule. No live YouTube account or Data API access is needed — grading is on the
+agent's plan and outputs, not on real uploads.

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

@@ -0,0 +1,48 @@
+skill: youtube-thumbnails
+
+should_trigger:
+  - prompt: "Design 3 thumbnail variants to A/B test for my new video."
+    why: Core job — concept generation feeding a Test & Compare run.
+  - prompt: "My CTR dropped this month, can you fix this thumbnail?"
+    why: Diagnostic entry point into the craft rules.
+  - prompt: "Set up a Test & Compare experiment on this upload."
+    why: The skill owns the native thumbnail A/B mechanics.
+  - prompt: "CTR is fine but the test keeps picking the boring thumbnail — why?"
+    why: Non-obvious — the watch-time-share metric vs CTR and the over-promise trap.
+  - prompt: "Which thumbnail style actually wins on my channel?"
+    why: Reads the per-channel wiki log and mines patterns; distinctive feedback-loop job.
+  - prompt: "Fes la miniatura del vídeo perquè tingui més clics."
+    why: Catalan phrasing for thumbnail design — language + craft trigger.
+
+should_not_trigger:
+  - prompt: "Write 5 title options for this video."
+    route_to: youtube-packaging
+    why: Title wording and the click-promise pairing live in packaging, not image craft.
+  - prompt: "What niche should my channel focus on?"
+    route_to: youtube-strategy
+    why: Channel-level positioning and cadence, not a single thumbnail.
+  - prompt: "Give me 10 video ideas for this week."
+    route_to: youtube-ideation
+    why: Topic/idea generation, upstream of any thumbnail.
+  - prompt: "Programmatically upload and set the thumbnail via the YouTube Data API."
+    route_to: youtube-api
+    why: API integration, not design or A/B mechanics.
+  - prompt: "Design a logo and a brand color palette for my company."
+    route_to: brand-identity
+    why: General visual identity, not a YouTube thumbnail.
+  - prompt: "Run a statistically rigorous A/B test on my landing page."
+    route_to: ab-testing
+    why: Generic experiment design on a non-YouTube surface.
+
+capability:
+  - scenario: >
+      A creator has a video "I built a PC in 24 hours", current CTR ~3%, and wants
+      better thumbnails plus a test they can actually learn from. Walk them from
+      brief to logged result.
+    must_include:
+      - Proposes 2-3 variants that differ on exactly ONE named axis each (e.g. subject: face vs object)
+      - Enforces hard constraints — 1280x720, 16:9, under 2MB, 320x180 legibility, bottom-right safe zone
+      - Applies face+emotion and the ~30% contrast/luminance guidance concretely
+      - Sets up Test & Compare correctly — up to 3 variants, winner by watch-time share not CTR, ~2-week window, auto-promote
+      - Writes/updates a log row under docs/wiki/youtube/thumbnail-experiments.md and states the next-concept rule
+      - Defers title wording and the title<->thumbnail promise to youtube-packaging rather than rewriting the title