@damiangilgonzalez/harness 1.3.7

package/skills/youtube-api/references/analytics-queries.md

@@ -0,0 +1,89 @@
+# Analytics API v2 — metric/dimension catalog + copy-paste queries
+
+Every report is the same shape:
+
+```text
+GET https://youtubeanalytics.googleapis.com/v2/reports
+  ?ids=channel==MINE
+  &startDate=YYYY-MM-DD
+  &endDate=YYYY-MM-DD
+  &metrics=<comma list>
+  &dimensions=<comma list>     (optional)
+  &filters=<key==value;...>    (optional)
+  &sort=<metric>               (optional)
+  &maxResults=<n>              (optional)
+```
+
+`ids=channel==MINE` reports on the authenticated user's channel.
+
+## Core metrics
+
+| Metric | Meaning |
+| --- | --- |
+| `views` | view count |
+| `estimatedMinutesWatched` | total watch time (minutes) |
+| `averageViewDuration` | mean seconds watched per view |
+| `averageViewPercentage` | mean % of the video watched |
+| `subscribersGained` / `subscribersLost` | net subs movement |
+| `likes`, `comments`, `shares` | engagement |
+| `audienceWatchRatio` | absolute retention at a playback position |
+| `relativeRetentionPerformance` | retention vs similar videos |
+| `impressions`, `impressionClickThroughRate` | **content-owner-report metrics** — see CTR note |
+| `estimatedRevenue` | needs `yt-analytics-monetary.readonly` scope |
+
+## Useful dimensions
+
+| Dimension | Use |
+| --- | --- |
+| `day` / `month` | time series |
+| `video` | per-video breakdown |
+| `elapsedVideoTimeRatio` | retention curve x-axis (0.0–1.0) |
+| `insightTrafficSourceType` | where views come from |
+| `country` | geography |
+| `deviceType` | mobile/desktop/TV/tablet |
+| `subscribedStatus` | `SUBSCRIBED` vs `UNSUBSCRIBED` |
+| `ageGroup`, `gender` | demographics |
+
+## Copy-paste query bodies (Python `yta.reports().query(...)`)
+
+```python
+# Daily time series for the month
+dict(ids="channel==MINE", startDate="2026-05-01", endDate="2026-05-31",
+     metrics="views,estimatedMinutesWatched,averageViewPercentage", dimensions="day")
+
+# Top videos by views
+dict(ids="channel==MINE", startDate="2026-05-01", endDate="2026-05-31",
+     metrics="views,estimatedMinutesWatched,averageViewPercentage",
+     dimensions="video", sort="-views", maxResults=10)
+
+# Retention curve for one video
+dict(ids="channel==MINE", startDate="2026-05-01", endDate="2026-05-31",
+     metrics="audienceWatchRatio,relativeRetentionPerformance",
+     dimensions="elapsedVideoTimeRatio", filters="video==VIDEO_ID")
+
+# Traffic sources
+dict(ids="channel==MINE", startDate="2026-05-01", endDate="2026-05-31",
+     metrics="views,estimatedMinutesWatched", dimensions="insightTrafficSourceType")
+
+# Geography
+dict(ids="channel==MINE", startDate="2026-05-01", endDate="2026-05-31",
+     metrics="views,estimatedMinutesWatched", dimensions="country", sort="-views")
+
+# Device + subscribed status
+dict(ids="channel==MINE", startDate="2026-05-01", endDate="2026-05-31",
+     metrics="views", dimensions="deviceType")
+dict(ids="channel==MINE", startDate="2026-05-01", endDate="2026-05-31",
+     metrics="views,averageViewPercentage", dimensions="subscribedStatus")
+```
+
+## `insightTrafficSourceType` values
+
+`YT_SEARCH` (search), `SUGGESTED` (suggested videos), `BROWSE` (home/subscriptions feed), `EXT_URL` (external sites), `NOTIFICATION`, `PLAYLIST`, `END_SCREEN`, `NO_LINK_EMBEDDED`, `NO_LINK_OTHER`, `CHANNEL`, `SUBSCRIBER`.
+
+## CTR / impressions: content-owner vs channel reports
+
+`impressions` and `impressionClickThroughRate` are surfaced through **content-owner reports**, not reliably through a plain `channel==MINE` query. If a channel query returns empty for them, that is expected — do not treat it as an error and do not block the pull. Read the CTR value from YouTube Studio for the wiki entry instead. Everything else (views, watch time, retention, traffic) is available on the channel query.
+
+## Valid combinations
+
+Not every metric pairs with every dimension. `audienceWatchRatio` requires the `elapsedVideoTimeRatio` dimension and a single-`video` filter. Demographic dimensions (`ageGroup`, `gender`) only return percentage-style metrics (`viewerPercentage`), not raw `views`. When a combination is invalid the API returns a `400` naming the offending field — fix by aligning metric and dimension from the tables above.

package/skills/youtube-api/references/oauth-setup.md

@@ -0,0 +1,55 @@
+# OAuth setup — GCP project to a refreshable YouTube token
+
+YouTube uses **user OAuth 2.0**. A human owns the channel; your code holds a refresh token that acts on their behalf. There is no service-account path for owning/uploading to a channel.
+
+## Step 1 — GCP project + enable both APIs
+
+In the Google Cloud console:
+
+1. Create or select a project.
+2. APIs & Services → Library → enable **YouTube Data API v3**.
+3. Enable **YouTube Analytics API** (same library). Forgetting this produces `403 ... API has not been used in project ... or it is disabled` the first time you call Analytics.
+
+## Step 2 — OAuth consent screen → "In production"
+
+1. APIs & Services → OAuth consent screen.
+2. User type **External** (unless you are inside a Workspace org).
+3. Add your scopes (see catalog below) and at least one test user *if* you stay in Testing.
+4. **Publish the app — set status to "In production."**
+
+Why this matters: while the app is in **Testing**, refresh tokens **expire after 7 days**. A cron that authed fine on Monday throws `invalid_grant` the next Monday. Publishing to production yields long-lived refresh tokens. For a personal script that never lists more than 100 users you do not need Google verification to flip to production; you only need verification for sensitive/restricted scopes shown to the public, but the token-lifetime fix applies the moment you publish.
+
+## Step 3 — Create the OAuth client
+
+| App type | When | Redirect |
+| --- | --- | --- |
+| **Desktop app** | Local/personal script, cron on your own box | loopback (`run_local_server`) — no redirect URI to register |
+| **Web application** | Hosted service with a callback URL | register the **exact** redirect URI, e.g. `https://app.example.com/oauth/callback` |
+
+Download the client JSON (`client_secret.json`). **Gitignore it.** It is not a public identifier — combined with a refresh token it is full channel access.
+
+## Scope catalog (request least privilege)
+
+| Scope | Grants |
+| --- | --- |
+| `https://www.googleapis.com/auth/youtube.upload` | upload videos only |
+| `https://www.googleapis.com/auth/youtube.force-ssl` | manage: edit/update/delete videos, set thumbnails |
+| `https://www.googleapis.com/auth/youtube` | full management (avoid unless you truly need it) |
+| `https://www.googleapis.com/auth/yt-analytics.readonly` | read non-monetary analytics |
+| `https://www.googleapis.com/auth/yt-analytics-monetary.readonly` | read revenue/monetary metrics |
+
+For the upload + edit + stats loop, the right set is `youtube.upload` + `youtube.force-ssl` + `yt-analytics.readonly`. Add the monetary scope only when you actually pull `estimatedRevenue`.
+
+## Token persistence + refresh
+
+The credential object refreshes its short-lived access token automatically *as long as you persist the refresh token*. See SKILL.md §2 for the Python (`google_auth_oauthlib` + `Credentials.from_authorized_user_file`) and Node (`OAuth2` + the `tokens` event) snippets. Always write the refreshed credential back to disk/secret store; in Node, only the first consent returns `refresh_token`, so capture it then.
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| `invalid_grant` after ~7 days | App in Testing | Publish consent screen to "In production"; re-consent once |
+| `unauthorized_client` | Wrong client type, or scope not added to consent screen | Match Desktop/Web to your flow; add the scope and re-consent |
+| `access_denied` | User not added as test user (Testing mode) or denied consent | Add test user, or publish; re-run flow |
+| `redirect_uri_mismatch` | Web client redirect not registered exactly | Register the literal callback URL, including scheme + path |
+| `403 insufficient permissions` | Token lacks the scope the call needs | Add scope, delete stored token, re-consent |

package/skills/youtube-api/references/wiki-schema.md

@@ -0,0 +1,91 @@
+# Wiki schema — `docs/wiki/youtube/`
+
+The point of this skill is not to print stats once; it is to grow a **feedback log** the strategy/packaging siblings can read. The log lives under `docs/wiki/youtube/` and every pull **appends** to it.
+
+`docs/wiki/` is an **OKF v0.1** bundle, so every non-reserved `.md` file written here carries YAML frontmatter with a non-empty `type`. This skill writes `type: youtube-metrics` on its snapshots/logs and keeps the domain keys (`date`, `range`, `channel`, `source`) that the strategy/packaging siblings parse literally — `type` and `timestamp` are added *alongside* them, never replacing them. OKF allows arbitrary extra keys, so the shared keys stay stable. Links between wiki files are standard markdown links (`[text](./file.md)`), never Obsidian wikilinks.
+
+## File tree
+
+```text
+docs/wiki/youtube/
+  index.md                  # rolling: pointer to latest snapshot + open questions
+  channel-2026-05-31.md     # one dated channel snapshot per pull
+  channel-2026-05-24.md
+  videos/
+    dQw4w9WgXcQ.md          # per-video running log, newest entry on top
+    abc123XYZ.md
+```
+
+Naming:
+
+- Channel snapshots: `channel-YYYY-MM-DD.md` (the pull date). One file per pull — never overwrite an earlier date.
+- Per-video logs: `videos/<VIDEO_ID>.md`. One file per video, **append** each new dated block at the top.
+- `index.md`: the only file that gets rewritten — it points at the latest snapshot and lists open questions for the siblings.
+
+## Channel snapshot template
+
+```markdown
+---
+type: youtube-metrics
+title: Channel snapshot 2026-05-31
+description: Channel KPIs and traffic for 2026-05-01..2026-05-31.
+tags: [youtube, channel-snapshot]
+timestamp: 2026-05-31T00:00:00Z
+date: 2026-05-31
+range: 2026-05-01..2026-05-31
+channel: MINE
+source: youtube-analytics-api-v2
+---
+## KPIs
+views: 41,233 | watch_min: 88,140 | avg_view_pct: 38.2% | avg_view_dur: 0:04:11
+subs: +312 / -41 (net +271)
+
+## Traffic (top 3 by views)
+BROWSE 44% · SUGGESTED 31% · YT_SEARCH 12%
+
+## What changed since last pull
+avg_view_pct +2.1pts; SUGGESTED share +6pts after the Ep.13 packaging change.
+```
+
+## Per-video log file — `videos/<VIDEO_ID>.md`
+
+The file carries frontmatter once (at the top); each new dated block is **prepended directly under the frontmatter** (newest entry first — this is an append-log, past entries are immutable). On the first write, create the frontmatter; on every later pull, refresh `timestamp` and insert the new block above the previous newest one. Keep the domain key `channel` so siblings can parse it.
+
+```markdown
+---
+type: youtube-metrics
+title: Video log — dQw4w9WgXcQ
+description: Per-pull KPI/traffic/retention log for video dQw4w9WgXcQ, newest entry first.
+tags: [youtube, video-log]
+timestamp: 2026-05-31T00:00:00Z
+channel: MINE
+source: youtube-analytics-api-v2
+---
+## 2026-05-31  (range 2026-05-01..2026-05-31)
+views: 8,902 | avg_view_pct: 41.0% | ctr(studio): 6.2%
+traffic: SUGGESTED 52% · BROWSE 23% · YT_SEARCH 9%
+retention: sharp 0.00→0.06 intro drop; second dip ~0.55; tail flat after 0.80
+note: held suggested-traffic share week over week.
+```
+
+## index.md
+
+OKF **reserved file**: a directory listing, so it carries **no frontmatter**. Point at the latest snapshot and tracked videos with standard markdown links (never wikilinks).
+
+```markdown
+# YouTube channel feedback log
+latest snapshot: [channel-2026-05-31.md](./channel-2026-05-31.md)
+videos tracked: [dQw4w9WgXcQ](./videos/dQw4w9WgXcQ.md), [abc123XYZ](./videos/abc123XYZ.md)
+
+## Open questions for strategy/packaging
+- Intro drop-off at 0.06 recurs across last 3 uploads — packaging or pacing?
+- SUGGESTED now beats BROWSE on new uploads — lean into series framing?
+```
+
+## Rules
+
+1. **Append, never overwrite.** A snapshot is a point in time; deleting it erases the trend. The history is the deliverable.
+2. **One source of truth for derived numbers.** Store what the API returned. Mark Studio-sourced values explicitly (`ctr(studio)`) so a reader knows it was not API-derived.
+3. **No interpretation in the log beyond a one-line "what changed."** Deeper reading ("we should change the hook") is the strategy/packaging sibling's job — this skill records, it does not prescribe.
+4. **Siblings read this tree.** Keep the domain frontmatter keys stable (`date`, `range`, `channel`, `source`) so a sibling can parse the latest snapshot without guessing. The OKF keys (`type`, `title`, `description`, `tags`, `timestamp`) are added alongside them, never instead of them — all four youtube skills share this same key set and the same markdown-link style.
+5. **OKF-conformant wiki content.** Every non-reserved `.md` here has a non-empty `type` (`youtube-metrics`). `index.md` is the lone reserved file (no frontmatter, a directory listing). Per-video logs are newest-first append-logs with ISO 8601 dates; past dated blocks are never edited. Cross-references use standard markdown links (`[text](./file.md)`), never `[[wikilinks]]`.

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

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# verify.sh — static, no-network preflight linter for YouTube API integration code.
+# Read-only. Flags the patterns this skill bans. Exits 0 on a clean/empty target,
+# non-zero with file:line on any hit.
+#
+# Usage: scripts/verify.sh [TARGET_DIR]   (default: current directory)
+
+set -euo pipefail
+
+TARGET="${1:-.}"
+hits=0
+
+if [ ! -d "$TARGET" ]; then
+  echo "verify.sh: target '$TARGET' is not a directory" >&2
+  exit 2
+fi
+
+report() { echo "FAIL [$1] $2"; hits=$((hits + 1)); }
+
+# Files we scan: source + config, skipping vendored/build/VCS dirs. (bash 3.2 compatible)
+FILES=()
+while IFS= read -r _f; do
+  [ -n "$_f" ] && FILES+=("$_f")
+done < <(
+  find "$TARGET" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/dist/*' \
+       -o -path '*/build/*' -o -path '*/.venv/*' -o -path '*/venv/*' \) -prune -o \
+    -type f \( -name '*.py' -o -name '*.js' -o -name '*.ts' -o -name '*.mjs' \
+       -o -name '*.json' -o -name '*.env' -o -name '*.yaml' -o -name '*.yml' \) -print 2>/dev/null
+)
+
+# (1) Committed OAuth secrets: client_secret*.json present, or token.json containing a refresh_token.
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  report "secret-file" "$f: OAuth client_secret file should not be tracked (gitignore it)"
+done < <(find "$TARGET" \( -path '*/.git/*' \) -prune -o -type f -name 'client_secret*.json' -print 2>/dev/null)
+
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  if grep -lqs 'refresh_token' "$f" 2>/dev/null; then
+    report "tracked-token" "$f: token file contains a refresh_token — do not commit it"
+  fi
+done < <(find "$TARGET" \( -path '*/.git/*' \) -prune -o -type f -name 'token*.json' -print 2>/dev/null)
+
+# Per-file content scans.
+for f in ${FILES[@]+"${FILES[@]}"}; do
+  [ -f "$f" ] || continue
+
+  # (2) Over-broad full-management scope where least-privilege would do.
+  while IFS= read -r line; do
+    report "full-scope" "$f:$line over-broad scope auth/youtube (use youtube.upload + yt-analytics.readonly)"
+  done < <(grep -nE 'auth/youtube"|auth/youtube'"'"'|auth/youtube[[:space:]]*$|auth/youtube,' "$f" 2>/dev/null \
+            | grep -vE 'youtube\.(upload|force-ssl|readonly)|yt-analytics' | cut -d: -f1)
+
+  # (3) videos.insert path with no resumable/uploadType and no retry/backoff helper in the same file.
+  # Code-structure check — only meaningful in source files, not config/prose.
+  case "$f" in
+    *.py|*.js|*.ts|*.mjs) ;;
+    *) continue ;;
+  esac
+  if grep -qE 'videos\(\)\.insert|videos\.insert' "$f" 2>/dev/null; then
+    if ! grep -qiE 'resumable|uploadType|next_chunk|MediaFileUpload' "$f" 2>/dev/null; then
+      ln=$(grep -nE 'videos\(\)\.insert|videos\.insert' "$f" 2>/dev/null | head -1 | cut -d: -f1)
+      report "no-resumable" "$f:${ln:-?} videos.insert with no resumable/uploadType — use the resumable protocol"
+    fi
+    if ! grep -qiE 'backoff|retry|sleep|next_chunk' "$f" 2>/dev/null; then
+      ln=$(grep -nE 'videos\(\)\.insert|videos\.insert' "$f" 2>/dev/null | head -1 | cut -d: -f1)
+      report "no-backoff" "$f:${ln:-?} videos.insert with no retry/backoff helper — back off on 403/429"
+    fi
+  fi
+
+  # (4) Hardcoded access_token / Bearer literal instead of a refreshable credential.
+  while IFS= read -r line; do
+    report "hardcoded-token" "$f:$line hardcoded access_token/Bearer — use a refreshable credential object"
+  done < <(grep -nE 'access_token[[:space:]]*=[[:space:]]*["'"'"']ya29\.|Authorization:[[:space:]]*Bearer[[:space:]]+ya29\.|Bearer[[:space:]]+ya29\.' "$f" 2>/dev/null | cut -d: -f1)
+done
+
+if [ "$hits" -gt 0 ]; then
+  echo "verify.sh: $hits issue(s) found in '$TARGET'"
+  exit 1
+fi
+
+echo "OK: no banned YouTube-API patterns found in '$TARGET'"
+exit 0

package/skills/youtube-ideation/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: youtube-ideation
+description: "Use when deciding which videos a channel should make next and tracking whether each bet beat baseline — generating, scoring and prioritising candidate ideas from the channel's own performance log plus outlier and search-trend research, then recording each promoted idea as a dated hypothesis with its measured outcome. NOT writing the title or thumbnail text for a chosen idea (that is `youtube-packaging`)."
+tags: [youtube, video-ideas, ideation, idea-validation, outlier-analysis, content-strategy, hypothesis-tracking, learning-loop, niche-research, prioritization]
+recommends: [youtube-strategy, youtube-packaging, youtube-thumbnails, youtube-api, competitor-watch, market-research]
+origin: risco
+---
+
+# youtube-ideation
+
+You decide **what to make next, and you learn from whether it worked**. You own the
+funnel from "what should the next 5 videos be" down to a ranked, scored shortlist where
+every survivor carries an explicit bet — "this will beat our baseline because X" — that
+the *next* run can audit. You are bets plus a scoreboard, not a brainstorm.
+
+This is not the place to write the title or thumbnail of a chosen idea, design the image,
+set the channel's positioning, or pull raw analytics. Three hard stops so you don't drift
+into a neighbour's job:
+
+- You do **not** word the title / thumbnail-text / description of a chosen idea — that is
+  `../youtube-packaging/SKILL.md`. You pick *which* idea; packaging picks *how it's worded*.
+- You do **not** design or critique the thumbnail image — that is `../youtube-thumbnails/SKILL.md`.
+- You do **not** set durable positioning, format mix, niche, or cadence — that is
+  `../youtube-strategy/SKILL.md`. Strategy is doctrine; you operate inside it.
+
+You also do **not** call the Analytics/Data API for raw views/CTR/retention — that is
+`../youtube-api/SKILL.md`. You *read* the performance log it produces. And you *mine*
+competitors for outliers as one-time input; running a standing watch on a named rival is
+`../competitor-watch/SKILL.md`.
+
+## What you produce
+
+Two coupled Markdown artifacts, both written to `docs/` so the next run sees them:
+
+1. **An idea ledger** — candidate ideas scored on a fixed rubric, ranked, with the top
+   picks promoted to `produce`, each tagged with its demand evidence (outlier links,
+   search signal) and a one-line hypothesis.
+2. **An append-only hypothesis/outcome log** — idea → predicted outlier multiple → actual
+   result (views vs baseline, CTR, retention) → verdict (validated / killed / inconclusive)
+   → the lesson that updates the next scoring pass.
+
+The single governing rule, said once and loudly:
+
+> **Every promoted idea carries a dated hypothesis with a predicted outlier multiple that
+> you WILL grade after publish.** An idea without a falsifiable bet does not get promoted.
+
+*Why:* "more ideas" never grew a channel; better, audited *decisions* do. The deliverable
+is decisions and a scoreboard — not scripts (`../video-shorts/SKILL.md`) and not images.
+
+Exact templates for both artifacts: `references/idea-ledger-and-loop.md`.
+
+## Read the log first — you cannot score what you can't measure
+
+Before you generate a single idea, load the channel performance history from `docs/`
+and compute each past video's **outlier multiple = views ÷ the channel's average views**.
+
+```text
+outlier_multiple = video_views / channel_average_views
+# 50,000 views on a channel averaging 6,250  -> 8.0x  (a real hit)
+# 500,000 views on a channel averaging 1,800,000 -> 0.3x  (a miss, despite the big number)
+```
+
+The multiple normalizes across channel size, so it is the only fair way to compare a small
+channel's win to a large one's — *why* you score "outlier signal" on the multiple, never on
+raw views.
+
+Decision at the top of every run:
+
+| Found in `docs/`? | Do this |
+| --- | --- |
+| A performance log with views per video | Use it. Compute the channel average → that is your **baseline**. |
+| Nothing | Bootstrap: compute the average from whatever videos you can get, write `baseline = N views (from M videos, YYYY-MM-DD)` to `docs/`, and say so out loud. |
+
+You cannot grade a hypothesis "vs baseline" if there is no baseline. The raw numbers are
+populated by `../youtube-api/SKILL.md` — you read them, you do not pull them.
+
+## Generate research-led, not blind
+
+The 2026 workflow that actually works is research-led, not brainstorm-led. Run these six
+steps in order — do not skip to step 6:
+
+1. Analyze the successful channels in the niche.
+2. Find their **outlier videos** (high multiple, not high raw views).
+3. Study the title + thumbnail patterns those outliers share.
+4. Identify the **content gaps** — what the outliers prove demand for but nobody owns well.
+5. Check audience + trend signals (next section).
+6. Generate **original variations** — your angle, not a copy.
+
+Two non-negotiable rules from the data:
+
+- **3x or better is a real signal; 2x is likely noise.** *Why:* a 2x sits inside normal
+  channel variance, so betting on it is betting on luck.
+- **Find 5–10 outliers and extract the shared trait.** *Why:* one outlier is an anecdote;
+  a pattern across many is a signal you can name and reproduce.
+
+```text
+Bad:  "Make a video about X because it's trending right now."
+Good: "Make OUR angle on X: 6 niche outliers (3.4x–7.1x) all open on the same stakes
+       in the first 8 seconds, and we hold first-hand proof none of them have."
+```
+
+Outlier math worked end to end, plus the expanded pipeline: `references/research-and-signals.md`.
+
+## Score on the rubric — a fixed scorecard beats vibes
+
+Score every surviving idea 1–5 on seven dimensions, sum to a total out of 35.
+
+| # | Dimension | 1 | 5 |
+| --- | --- | --- | --- |
+| 1 | Audience fit | off-niche | dead center for our core viewer |
+| 2 | Proven demand | no signal | strong search/trend evidence on the row |
+| 3 | Outlier signal | no outliers found | 5+ niche outliers at 3x+ share the trait |
+| 4 | Packaging potential | hard to title/thumbnail | obvious strong title + thumbnail exist |
+| 5 | Retention potential | thin payoff | a hook + payoff that holds to the end |
+| 6 | Originality | a copy of an outlier | a genuinely new angle / unique proof |
+| 7 | Monetization fit | off-brand for sponsors | natural fit for our revenue |
+
+Verdict bands (out of 35):
+
+- **30–35 → produce.** Promote it (and it must carry a hypothesis — see below).
+- **24–29 → improve the angle first**, then rescore.
+- **18–23 → gray middle**: re-angle or shelve; do not produce as-is.
+- **under 18 → abandon.** Say why in one line so the next run doesn't re-raise it.
+
+Worked example — two ideas, same niche:
+
+| Idea | Fit | Demand | Outlier | Pkg | Ret | Orig | Money | Total | Verdict |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| "I rebuilt X the way the pros do" | 5 | 4 | 5 | 5 | 4 | 4 | 4 | **31** | produce |
+| "My honest thoughts on X this year" | 4 | 2 | 2 | 2 | 3 | 3 | 3 | **19** | re-angle (gray) |
+
+*Why a fixed rubric:* it makes "no" defensible and makes every hypothesis comparable across
+runs — without it, last month's score and this month's score mean nothing to each other.
+
+## Validate demand before committing a week of editing
+
+Three fast pre-tests before any idea earns `produce`:
+
+1. Can you state the idea in **one sentence**? If not, it isn't ready.
+2. Does it serve the **core audience AND** have reach to **new** viewers? Need both.
+3. Does **search/trend demand** exist for the topic? Prove it, don't assume it.
+
+Where to get the signal:
+
+| Free (use first) | Paid (for real volume numbers) |
+| --- | --- |
+| YouTube Studio **Trends** tab — top searches for *your* audience + saved topics, last 28 days | OutlierKit, Keywords Everywhere |
+| Google Trends (direction, seasonality) | vidIQ (volume + trending, ~50 Daily Ideas/day) |
+| YouTube **autocomplete** (real query phrasings) | TubeBuddy (weights score vs *your* channel authority), Semrush |
+
+Hard rule: **record the evidence on the idea's ledger row** — the outlier links and the
+search number. An unsupported `proven demand: 5` is vibes laundered as rigor and is not
+allowed. (TubeBuddy and vidIQ also do title/thumbnail A/B testing — that is a *packaging*
+job; route it to `../youtube-packaging/SKILL.md`.) Source table: `references/research-and-signals.md`.
+
+## Write the hypothesis, then promote
+
+Every `produce`-tier idea gets a bet in this exact shape:
+
+```text
+idea → predicted outlier multiple → why (the mechanism) → judge-by metric (vs baseline) → date
+```
+
+```text
+Bad:  "This one should do well."
+Good: "Predict 2.5x baseline. Bet: the contrarian title + we own first-hand proof no
+       outlier has. Judge by 28-day views vs trailing-10 average AND CTR vs channel
+       median. 2026-06-02."
+```
+
+Promote the **top 3–5** by score (default). Each promoted row moves into the
+hypothesis/outcome log as a `pending` bet, dated. Template:
+`references/idea-ledger-and-loop.md`.
+
+## Close the loop — the part most creators skip
+
+This is why the skill exists. After the video publishes, **append** an outcome row to the
+log:
+
+- actual outlier multiple, CTR, retention vs baseline;
+- **verdict**: `validated` / `killed` / `inconclusive`;
+- the **lesson** that adjusts the next scoring pass.
+
+| Verdict | What it means | What it changes next run |
+| --- | --- | --- |
+| validated | beat the predicted multiple | double down on the shared trait that worked |
+| killed | missed baseline clearly | demote that dimension's weight for similar ideas |
+| inconclusive | too small a sample / confounded | note the confound, re-run, don't conclude |
+
+Hard rules: the log is **append-only and dated**. **Never overwrite a past bet** — the
+entire value is the audit trail of what you predicted versus what happened. A log you can
+rewrite teaches you nothing.
+
+## 2026 context that weights the bet
+
+- **Shorts-first storytelling is the dominant discovery force.** Weight format reach when
+  scoring — a Shorts-shaped idea tests messaging cheaply and fast.
+- **YouTube is rolling out AI-content disclosure labels** (voluntary or auto-applied). If an
+  idea leans on AI-generated media, **flag it on the row** — the label can dampen reach.
+
+Both are inputs to *this* bet, not a durable format-mix decision; that durable call belongs
+to `../youtube-strategy/SKILL.md`. Dated notes: `references/research-and-signals.md`.
+
+## Anti-patterns
+
+| Bad | Why it costs you | Good |
+| --- | --- | --- |
+| Brainstorm 50 ideas with no channel data | "outlier signal" becomes fiction | read the log + find real outliers first |
+| Promote an idea with no hypothesis | you can't learn from the outcome | every `produce` idea gets a falsifiable bet |
+| Treat one outlier as a trend | anecdote, not signal | require 5–10 outliers sharing a trait |
+| Overwrite the log when a bet fails | destroys the audit trail | append-only, dated, never rewrite |
+| Chase a 2x like it's a hit | inside normal variance — likely noise | use the 3x+ threshold |
+| Score "proven demand: 5" with no evidence | vibes laundered as rigor | attach outlier links + a search number |
+| Write the title/thumbnail here | wrong skill | route to youtube-packaging / youtube-thumbnails |
+| Run ideation as a one-shot | no learning loop | outcomes feed the next scoring pass |
+
+## Verify + references
+
+Lint a produced ledger before you trust it:
+
+```bash
+scripts/verify.sh path/to/idea-ledger.md
+```
+
+It is read-only: it checks every idea is scored on all 7 dimensions with a /35 total that
+matches its verdict band, every `produce` idea carries a hypothesis + numeric predicted
+multiple + judge-by metric, and the outcome log is append-only-shaped (dated rows; each bet
+either `pending` or carrying `actual + verdict + lesson`). An empty/clean target is a skip,
+never a failure.
+
+- Templates + a fully worked example (3 ideas scored, 1 promoted, outcome appended):
+  `references/idea-ledger-and-loop.md`.
+- Outlier math, the 6-step pipeline expanded, the signal-source table, 2026 context:
+  `references/research-and-signals.md`.

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

@@ -0,0 +1,14 @@
+# Evals — youtube-ideation
+
+Read or run `cases.yaml` manually, or via the catalog eval harness. The `should_trigger` /
+`should_not_trigger` prompts confirm the description fires on real "what to make next / did
+it work" asks (including the non-obvious learning-loop ones and the Spanish phrasing) and
+routes near-misses to the correct YouTube sibling — packaging for the title/thumbnail words,
+thumbnails for the image, strategy for durable positioning, youtube-api for raw data,
+video-shorts for the script. The `capability` case is graded by inspecting a generated idea
+ledger + hypothesis/outcome log against its `must_include` rubric: it must compute an outlier
+baseline, ground ideas in named 3x+ outliers (not a blind brainstorm), score all 7
+dimensions to a /35 with the right verdict band, attach a dated hypothesis with a predicted
+multiple and a judge-by metric to every promoted idea, and define the append-only outcome
+log. `scripts/verify.sh <ledger.md>` is the static lint that backs the structural half of
+that rubric; it is read-only and skips cleanly on an empty target.

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

@@ -0,0 +1,52 @@
+skill: youtube-ideation
+
+should_trigger:
+  - prompt: "What should my next 5 YouTube videos be? Rank them for my channel."
+    why: Core ask — generate and prioritize a ranked shortlist for this channel.
+  - prompt: "Score these 12 ideas and tell me which ones to actually produce."
+    why: Rubric scoring down to a produce/improve/abandon shortlist is the skill's center.
+  - prompt: "Find content gaps and 3x+ outliers in my niche I could win."
+    why: Outlier/gap research is step 2-4 of the research-led pipeline.
+  - prompt: "My last video flopped — log the result and adjust what we pick next."
+    why: Non-obvious — the back-half learning loop (append outcome, update next scoring) most
+      creators skip; this skill owns it.
+  - prompt: "Which of our past video bets actually beat baseline, and what's the pattern?"
+    why: Non-obvious — reading the append-only hypothesis/outcome log to find validated bets.
+  - prompt: "Qué vídeo grabo ahora? Dame ideas priorizadas y valida la demanda antes de grabar."
+    why: Spanish — full ideation + demand-validation ask before committing to production.
+  - prompt: "Is there real search demand for this topic before I commit a week of editing?"
+    why: Demand pre-test (search/trend signal) gating an idea before production.
+
+should_not_trigger:
+  - prompt: "Write the title and thumbnail text for this video I'm making."
+    route_to: youtube-packaging
+    why: Wording the sell of an already-chosen idea, not picking which idea — packaging's job.
+  - prompt: "Design a high-contrast thumbnail with my face for this video."
+    route_to: youtube-thumbnails
+    why: Image composition/craft, not idea selection.
+  - prompt: "Set my channel's niche, format mix, and upload cadence for the year."
+    route_to: youtube-strategy
+    why: Durable positioning doctrine; ideation operates inside it, it does not set it.
+  - prompt: "Pull my last 30 videos' views, CTR, and retention curves from the API."
+    route_to: youtube-api
+    why: Raw data plumbing; this skill reads the log the API produces, it does not call it.
+  - prompt: "Write the 8-minute script for this explainer video."
+    route_to: video-shorts
+    why: Scripting / edit direction of a chosen video, not deciding which video to make.
+
+capability:
+  - scenario: >
+      Given a small channel performance log (a stated baseline plus a handful of past videos
+      with view counts) and a niche, produce a ranked idea ledger and promote the top picks
+      with hypotheses.
+    must_include:
+      - Computes or uses an outlier baseline (views divided by channel average views).
+      - Generates ideas grounded in named outliers (3x+ examples), not a blind brainstorm.
+      - Requires 5-10 outliers with a shared trait, not a single anecdote.
+      - Scores each idea on all 7 rubric dimensions with a /35 total.
+      - Applies the correct verdict band (>=30 produce, 24-29 improve, 18-23 gray, <18 abandon).
+      - Every promoted idea carries a dated hypothesis with a predicted outlier multiple AND a
+        judge-by metric vs baseline.
+      - Records demand evidence (outlier links + search number) on each scored row.
+      - Defines the append-only hypothesis/outcome log shape to grade the bets later.
+      - Routes title/thumbnail work out to youtube-packaging / youtube-thumbnails.