rsc-universal 0.1.1

package/skills/shortform-editing/scripts/verify.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# verify.sh — assert a produced vertical short MP4 meets the export spec.
+#
+# Usage:
+#   bash scripts/verify.sh path/to/out.mp4   # check one produced short
+#   bash scripts/verify.sh path/to/dir       # scan dir for *.mp4
+#   bash scripts/verify.sh                    # no target -> nothing to check, exit 0
+#
+# What it asserts (when ffprobe is available):
+#   1. Video width  == 1080
+#   2. Video height == 1920  (i.e. 9:16 vertical)
+#   3. Video codec  == h264
+#   4. Audio codec  == aac
+#   5. Frame rate in {30, 60}
+#   6. A sibling caption file (<name>.ass / <name>.srt, or any *.ass/*.srt next to
+#      the mp4) exists and is non-empty.
+#
+# Fallback (no ffprobe): static check only — the target is an .mp4 file and a
+# sibling .ass/.srt caption file exists and is non-empty. It cannot read codecs.
+#
+# Read-only: never writes, installs, or touches the network. Pure inspection.
+# Exits 0 on a clean target AND on an empty/clean target (no false failure):
+#   - no argument               -> "nothing to check", exit 0
+#   - directory with no *.mp4    -> "nothing to check", exit 0
+# Exits non-zero only when a real, probeable file breaks a rule.
+#
+# Portability: stock macOS bash 3.2. set -u on; set -e intentionally off.
+
+set -u
+
+if [ -t 1 ] && command -v tput >/dev/null 2>&1; then
+  RED="$(tput setaf 1)"; GREEN="$(tput setaf 2)"; YELLOW="$(tput setaf 3)"; RESET="$(tput sgr0)"
+else
+  RED=""; GREEN=""; YELLOW=""; RESET=""
+fi
+
+failures=0
+fail() { printf '%s\n' "${RED}FAIL: $1${RESET}"; failures=$((failures + 1)); }
+warn() { printf '%s\n' "${YELLOW}WARN: $1${RESET}"; }
+ok()   { printf '%s\n' "${GREEN}OK: $1${RESET}"; }
+
+# --- collect targets -------------------------------------------------------
+if [ "$#" -eq 0 ]; then
+  printf '%s\n' "${YELLOW}Nothing to check (no MP4 path given). Pass an output .mp4 to verify.${RESET}"
+  exit 0
+fi
+
+targets=""
+for arg in "$@"; do
+  if [ -d "$arg" ]; then
+    for f in "$arg"/*.mp4 "$arg"/*.MP4; do
+      [ -e "$f" ] && targets="${targets}${targets:+
+}$f"
+    done
+  elif [ -f "$arg" ]; then
+    targets="${targets}${targets:+
+}$arg"
+  else
+    warn "Skipping '$arg' (not a file or directory)."
+  fi
+done
+
+if [ -z "$targets" ]; then
+  printf '%s\n' "${YELLOW}No .mp4 files found in the target(s). Nothing to check.${RESET}"
+  exit 0
+fi
+
+HAVE_FFPROBE=0
+command -v ffprobe >/dev/null 2>&1 && HAVE_FFPROBE=1
+[ "$HAVE_FFPROBE" -eq 0 ] && warn "ffprobe not found — falling back to a static path/caption check (no codec inspection)."
+
+# --- caption sibling check -------------------------------------------------
+# A non-empty .ass or .srt next to the mp4 (same basename preferred, else any).
+caption_for() {
+  mp4="$1"
+  dir=$(dirname "$mp4")
+  base=$(basename "$mp4")
+  stem="${base%.*}"
+  for cand in "$dir/$stem.ass" "$dir/$stem.srt"; do
+    if [ -s "$cand" ]; then printf '%s' "$cand"; return 0; fi
+  done
+  for cand in "$dir"/*.ass "$dir"/*.srt; do
+    if [ -s "$cand" ]; then printf '%s' "$cand"; return 0; fi
+  done
+  return 1
+}
+
+# --- per-target checks -----------------------------------------------------
+OLDIFS="$IFS"; IFS='
+'
+for mp4 in $targets; do
+  IFS="$OLDIFS"
+  printf '\n== %s ==\n' "$mp4"
+
+  if [ "$HAVE_FFPROBE" -eq 1 ]; then
+    W=$(ffprobe -v error -select_streams v:0 -show_entries stream=width  -of csv=p=0 "$mp4" 2>/dev/null)
+    H=$(ffprobe -v error -select_streams v:0 -show_entries stream=height -of csv=p=0 "$mp4" 2>/dev/null)
+    VC=$(ffprobe -v error -select_streams v:0 -show_entries stream=codec_name -of csv=p=0 "$mp4" 2>/dev/null)
+    AC=$(ffprobe -v error -select_streams a:0 -show_entries stream=codec_name -of csv=p=0 "$mp4" 2>/dev/null)
+    FR=$(ffprobe -v error -select_streams v:0 -show_entries stream=avg_frame_rate -of csv=p=0 "$mp4" 2>/dev/null)
+
+    [ "$W" = "1080" ] && ok "width 1080" || fail "width is '$W' (expected 1080)"
+    [ "$H" = "1920" ] && ok "height 1920 (9:16)" || fail "height is '$H' (expected 1920)"
+    [ "$VC" = "h264" ] && ok "video codec h264" || fail "video codec is '$VC' (expected h264)"
+    [ "$AC" = "aac" ] && ok "audio codec aac" || fail "audio codec is '$AC' (expected aac)"
+
+    # avg_frame_rate is a rational like 30/1 or 60000/1001; reduce to an integer fps.
+    FPS=""
+    case "$FR" in
+      */*)
+        num="${FR%%/*}"; den="${FR##*/}"
+        if [ -n "$den" ] && [ "$den" != "0" ]; then
+          FPS=$(awk -v n="$num" -v d="$den" 'BEGIN{printf "%d", (n/d)+0.5}')
+        fi
+        ;;
+      *) FPS="$FR" ;;
+    esac
+    if [ "$FPS" = "30" ] || [ "$FPS" = "60" ]; then
+      ok "frame rate ${FPS} fps"
+    else
+      fail "frame rate is '$FR' (~${FPS} fps; expected 30 or 60)"
+    fi
+  else
+    case "$mp4" in
+      *.mp4|*.MP4) ok "is an .mp4 file" ;;
+      *) fail "not an .mp4 file: $mp4" ;;
+    esac
+  fi
+
+  if cap=$(caption_for "$mp4"); then
+    ok "caption file present and non-empty: $(basename "$cap")"
+  else
+    fail "no non-empty sibling .ass/.srt caption file next to $(basename "$mp4")"
+  fi
+
+  IFS='
+'
+done
+IFS="$OLDIFS"
+
+printf '\n'
+if [ "$failures" -eq 0 ]; then
+  ok "all checks passed"
+  exit 0
+else
+  fail "$failures check(s) failed"
+  exit 1
+fi

package/skills/shortform-ideation/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: shortform-ideation
+description: "Use when an account that already posts (or is about to start posting) Reels/TikTok/Shorts needs a ranked batch of next video ideas grounded in its own performance log plus live trending sounds/formats/hashtags, and a ledger that ties each idea-bet to its measured outcome. Use to fold this week's trending audio into ideas, to decide which 3 of 12 ideas to shoot first, or to review why the bets you made flopped. Triggers: 'give me 10 Reels ideas for next week', 'which of these ideas do we make first', 'fold this week's trending TikTok sounds into our idea list', 'why did the ones we bet on last month flop', 'idea backlog for our TikTok', 'idéame Reels para esta semana basándote en lo que ya nos funcionó', 'prioritza idees de vídeo curt per aquesta setmana'. NOT writing the shot-by-shot script or edit decision sheet for a chosen idea (that is video-shorts), NOT setting cadence/pillars/positioning (that is shortform-strategy), NOT captions/covers/hashtag-sets for a finished cut (that is shortform-packaging)."
+tags: [shortform, reels, tiktok, ideation, content-ideas, trend-jacking, experiment-log]
+recommends: [video-shorts, shortform-strategy, shortform-packaging, analytics, content-engine]
+origin: risco
+---
+
+# Shortform Ideation — The Idea Engine and the Bet Ledger
+
+*You run the closed loop for a Reels/TikTok/Shorts account: hypothesis → bet → measured outcome → a better next batch.* You own the idea list, the priority score, and the experiment ledger. You do not write the spoken lines, you do not pick the cadence, and you do not finalize the caption.
+
+**Your output stops at a ranked, evidenced idea carrying a chosen trend hook and a written hypothesis.** The moment you start writing spoken lines or beat timecodes, you have crossed into `video-shorts`. Hand off; do not squat.
+
+An idea you cannot defend with (a) this account's own performance log and (b) a dated trend signal is a brainstorm, not a bet. This skill refuses to emit a brainstorm dump.
+
+## Decision gate — are you even in ideation?
+
+Read the ask against this table before you generate anything. *Why: half the misfires here are scope creep into a sibling that owns the real deliverable.*
+
+| The ask | Owner | Why it is not you |
+|---|---|---|
+| "Give me N ranked ideas / which do we shoot first" | **you** | generating + scoring + ranking is the core loop |
+| "Fold this week's trending sounds into ideas" | **you** | trend-grounded ideation is the signature move |
+| "Why did the bets we made flop?" | **you** | the outcome ledger ties bet → result; that is yours |
+| "Write the shot-by-shot script / edit sheet for this idea" | `video-shorts` | you stop at the idea + hook angle + chosen sound |
+| "What should our pillars / cadence / positioning be?" | `shortform-strategy` | you consume pillars as input, you do not set them |
+| "Write the caption + hashtags + cover for this finished cut" | `shortform-packaging` | you may *suggest* a hashtag as a trend signal, not finalize one |
+| "YouTube ideas with thumbnail-first packaging" | `youtube-ideation` | that pipeline is packaging-led and decays slower |
+| "Run the cross-channel calendar across blog/email/social" | `content-engine` | you feed ranked ideas *into* a calendar, you don't run it |
+| "Build me a metrics dashboard" | `analytics` | you *read* the perf log to score ideas, you don't build reporting |
+
+## The loop — four phases, in order
+
+```text
+Phase 1 GROUND        Phase 2 SOURCE TRENDS     Phase 3 GENERATE+SCORE   Phase 4 LOG THE BET
+read 02-DOCS perf  ─▶ capture dated trend    ─▶ idea = topic × format ─▶ write hypothesis to
+log; pull winning     signals (legally, no       × trend-hook × pacing    02-DOCS/shortform/
+hooks/formats and     scraping); flag stale      → score → rank backlog   experiments/, leave
+proven flops          signals                                             result fields pending
+```
+
+**Never skip Phase 1.** Ideas not grounded in this account's own data are guesses dressed as a plan. Grounding is what makes the score mean something. *Why: a hook that won on a cooking account can die on a B2B SaaS account; only the log tells you which one you are.*
+
+## Phase 1 — Ground in 02-DOCS
+
+The account's performance log lives at `02-DOCS/shortform/performance.md` (or `performance.csv`). Read it first, every cycle.
+
+Extract four things and keep them in working memory for scoring:
+
+1. **Winning hooks** — the opening 1–3s patterns that earned >60% 3s-hold.
+2. **Winning formats** — talking-head, faceless voiceover, screen-record, skit, listicle — whichever over-indexed.
+3. **Dead topics/formats** — what under-indexed twice or more. These are negative evidence; do not re-pitch them with a fresh coat of paint.
+4. **Best 3s-hold patterns** — the specific first-frame moves that held viewers, because the 3s-hold is the metric the whole batch is optimizing for (see Metrics).
+
+**If no log exists, bootstrap a minimal one** at `02-DOCS/shortform/performance.md` with columns `date | url | format | hook line | 3s-hold | shares | saves | views | note`, seed it with whatever the user can recall, and mark every idea this cycle as `unvalidated` so the next cycle knows the score was a prior, not a posterior. *Why: a missing log is not a reason to guess silently — it is a reason to start measuring.*
+
+## Phase 2 — Source trends (legally)
+
+Capture trending sounds, formats, and hashtags and **date every single signal**, because short-form trend windows are short and a stale signal is worse than no signal.
+
+**Hard rule: never scrape. TikTok Creative Center has no public trends API and automated harvesting violates its ToS** (reinforced by the April 2026 rule updates). Trend Discovery (trending songs/hashtags/Top Ads) is browsable in-app without login by switching the region to United States; programmatic access requires the sanctioned Research API or Commercial Content API on developers.tiktok.com. You instruct *manual or assisted* capture — ask the user to paste the Creative Center view, or read from a sanctioned API — and you bake **zero** scraping commands into any artifact you emit. *Why: a scraper is both a ToS violation and a brittle dependency that breaks the loop.*
+
+Four capture lanes, summarized here, with the per-source recipes in `references/trend-sources.md`:
+
+- **TikTok Creative Center** — region-switch to US, and **compare 7-day vs 30-day movement.** Data refreshes every 24–48h. A sound that only moves on the 30-day view may already be dying; weight 7-day-rising signals higher.
+- **Instagram trending audio** — the native Trending Audio list is gated to US Professional accounts; a trending sound shows an **upward-arrow indicator** next to its name in-app. Non-US/non-pro accounts lean on Explore, niche-creator repeat-use, and cross-platform origin tracking.
+- **TikTok → Reels lead window** — Reels trends often lag TikTok by **3–7 days.** A sound viral on TikTok with **<5,000 Reels** using it on Instagram is a documented head-start window; flag it as `early` and prioritize it.
+- **Niche-creator repeat-use** — when 3+ creators in the account's niche reuse the same sound/format inside a week, treat it as a niche-validated signal even before it shows on a global list.
+
+Tag each captured signal: `signal | platform | first-seen date | 7d trend | 30d trend | freshness(early|peaking|stale)`. A signal with no date does not enter Phase 3.
+
+## Phase 3 — Generate + score
+
+**An idea is a product, not a topic:**
+
+```text
+idea = topic × format × trend-hook × pacing-archetype
+```
+
+- **topic** — drawn from the account's pillars and winning topics (Phase 1).
+- **format** — a winning format from the log, or one deliberate experiment.
+- **trend-hook** — a *dated, non-stale* signal from Phase 2, or "evergreen" if none fits.
+- **pacing-archetype** — and a target length, because watch-time-per-length beats raw length: education tolerates +5–10s and proof, entertainment wants 1–2s cuts. Attach a target length so the bet is testable.
+
+Score every idea on a weighted 1–5 rubric. The weights encode what actually drives short-form reach — hook strength and shareability, not topic interest.
+
+| Criterion | Weight | What 5 looks like |
+|---|---|---|
+| Hook strength | ×3 | first 3s opens a loop / pattern-break that matches a proven winning hook |
+| On-account fit | ×2 | topic+format both over-indexed in this account's log; never a proven flop |
+| Trend freshness | ×2 | 7-day-rising sound, or TikTok→Reels `early` (<5k Reels) window |
+| Shareability / save | ×2 | viewer has a clear reason to send or save it (utility, status, "this is so us") |
+| Effort (inverse) | ×1 | low production lift; score 5 = shoot today with what you have |
+
+`weighted_score = 3·hook + 2·fit + 2·fresh + 2·share + 1·(6−effort)` → max 50. Rank descending into the backlog.
+
+**Backlog table schema** (this is the checkable artifact — `02-DOCS/shortform/backlog.md`):
+
+| id | idea | hook line | trend signal + date | format | target len | score | status |
+|---|---|---|---|---|---|---|---|
+| SF-001 | … | … | … (2026-06-01, 7d↑) | … | … | 42 | planned |
+
+`status` ∈ `{planned, shooting, posted, killed}`.
+
+**Bad → Good idea:**
+
+- **Bad:** "Do a video about our espresso machine." — a topic with no hook, no format, no trend, no score. Unrankable.
+- **Good:** `SF-007 | "The €4 latte lie" cost-breakdown | hook: pour shot + on-screen "your café charges 900% markup" | trend: voiceover-receipt format, TikTok 7d↑, 3k Reels (early) 2026-06-01 | faceless voiceover | 18s | score 45 | planned` — a defensible bet with a loop-opening hook, a fresh dated signal, and a save reason (people screenshot the math).
+
+## Phase 4 — Log the bet
+
+Every idea you advance to `shooting`/`posted` gets a hypothesis file at `02-DOCS/shortform/experiments/<YYYY-MM-DD>-<slug>.md`. Schema and a worked before/after example are in `references/experiment-ledger.md`.
+
+The hypothesis is one falsifiable sentence:
+
+> **Hypothesis:** *trend* `voiceover-receipt` **+ hook** `"900% markup"` **will lift** `3s-hold` **above** `60%` **for topic** `café pricing`.
+
+Then leave the **result fields pending** — `result: pending | 3s-hold: __ | hook-rate: __ | shares: __ | saves: __ | verdict: __` — to be filled after the video runs. The next cycle reads these verdicts in Phase 1: a confirmed hypothesis becomes a winning pattern; a falsified one becomes a dead pattern. *Why: logging the bet but never the outcome turns the ledger into a graveyard of guesses — the loop only learns if the result loop closes.*
+
+## Metrics that matter
+
+Score and judge on these, not on raw views. *Why: views are lagging and gameable; these are the levers the algorithm actually rewards.*
+
+| Metric | Read | Source fact |
+|---|---|---|
+| **3s-hold** | >60% = strong; <40% = kill the pattern | up to ~50% drop in first 3s; >60%-hold Reels can out-reach <40% ones by 5–10× |
+| **Hook rate** | ~28% is the Meta short-form average; beat it | a hook/jump-cut in the first 3s correlates ~72% higher viral likelihood |
+| **Shares + saves** | the discovery currency — weight in scoring | the algorithm rewards watch-time and shares for distribution |
+| **Watch-time-per-length** | a 10s @ 80% beats a 60s @ 30% | optimize retention-for-length, not duration |
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| Brainstorm dump with no scores | unrankable; the user can't decide what to shoot first | always emit the ranked backlog table with a score per idea |
+| Chasing a 30-day-only trending sound | 30-day-only movement often means the sound is already dying | weight 7-day-rising; flag 30d-only as `stale` |
+| Re-pitching a topic the log proved dead | ignores the account's own negative evidence | check Phase-1 flops before scoring; never pitch a proven flop |
+| Scraping Creative Center for trends | violates ToS, breaks the loop, ships brittle code | manual/assisted capture or sanctioned API; zero scrape commands in artifacts |
+| Scoring by topic interest, not hook strength | a fascinating topic with a dead first 3s still flops | hook strength carries ×3 weight; score the first frame first |
+| Logging the bet but never the outcome | the loop never learns; next batch re-guesses | leave result fields and fill them; Phase 1 reads the verdicts |
+| Writing the full script/timecodes here | crosses into `video-shorts`; muddies the idea ledger | stop at hook line + chosen sound; hand off |
+| Capturing a trend signal with no date | freshness is unscorable; you may brief a dead sound | every signal carries a first-seen date or it doesn't enter Phase 3 |
+
+## Hand-off
+
+- Chosen an idea and need the shot-by-shot script + edit decision sheet? → [`../video-shorts/SKILL.md`](../video-shorts/SKILL.md).
+- Missing the pillars/cadence/positioning the ideas should fit inside? → `shortform-strategy` (it owns strategy; you consume it).
+- The cut exists and needs caption/cover/hashtag-set? → `shortform-packaging`.
+- Feeding the ranked backlog into a multi-channel calendar? → [`../content-engine/SKILL.md`](../content-engine/SKILL.md).
+- Long-form/YouTube idea pipeline instead? → [`../youtube-ideation/SKILL.md`](../youtube-ideation/SKILL.md).
+
+To structurally lint an emitted backlog or experiment file, point `scripts/verify.sh` at it (read-only): `bash scripts/verify.sh 02-DOCS/shortform/`.

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

@@ -0,0 +1,20 @@
+# Evals — shortform-ideation
+
+These cases are routing + capability checks for a human or an LLM judge; the only
+automated runner that ships with the skill is `scripts/verify.sh`, which structurally
+lints an emitted backlog or experiment file, not these prompts. To run the routing
+checks, feed each `should_trigger` prompt to the router and confirm the skill's
+`description` fires — including the non-obvious "why did the ones we bet on flop"
+(an outcome-ledger review that looks like analytics but is this skill's loop), the
+Spanish "idéame Reels para esta semana basándote en lo que ya nos funcionó", and the
+Catalan "prioritza idees de vídeo curt" phrasing — and confirm each
+`should_not_trigger` prompt routes to its named sibling (`video-shorts`,
+`shortform-strategy`, `shortform-packaging`, `youtube-ideation`, `analytics`) instead
+of here. For the `capability` scenario, generate the batch and grade it line by line
+against `must_include`: it must ground in the 02-DOCS perf log (re-using winning
+hooks, never re-pitching the dead topic), capture at least one dated trend signal
+with no scraping, emit the ranked backlog table with all required columns, score by
+hook strength + shareability rather than topic interest, write at least one bet as a
+dated pending-result hypothesis, and hand the chosen idea off to video-shorts rather
+than writing a script. To lint an actual produced artifact, point
+`scripts/verify.sh` at the file or the `02-DOCS/shortform/` directory.

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

@@ -0,0 +1,58 @@
+skill: shortform-ideation
+
+# Prompts that MUST load `shortform-ideation`. The skill owns the IDEA LOOP for a
+# Reels/TikTok/Shorts account: ground in the account's own perf log, fold in dated
+# trending signals (no scraping), generate + score + rank a backlog, and log each
+# bet as a hypothesis with result fields. It does NOT script/edit one video
+# (video-shorts), set pillars/cadence (shortform-strategy), package a finished cut
+# (shortform-packaging), do YouTube ideation (youtube-ideation), run a cross-channel
+# calendar (content-engine), or build dashboards (analytics).
+should_trigger:
+  - prompt: "Give me 10 Reels ideas for next week for our coffee brand."
+    why: "Core ask — generate a ranked batch of short-form ideas is the skill's primary deliverable."
+
+  - prompt: "We have 12 ideas — which 3 do we shoot first?"
+    why: "Prioritization/scoring of an idea set is core; the skill ranks into a backlog rather than dumping."
+
+  - prompt: "Fold this week's trending TikTok sounds into our idea list."
+    why: "Trend-grounded ideation — capturing dated trend signals and turning them into scored ideas is Phase 2→3."
+
+  - prompt: "Why did the videos we bet on last month flop?"
+    why: "Non-obvious — sounds like analytics, but reviewing the outcome ledger that ties each bet to its measured result is THIS skill's loop, not generic reporting."
+
+  - prompt: "Idéame Reels para esta semana basándote en lo que ya nos funcionó."
+    why: "Spanish for 'come up with Reels for this week based on what already worked for us' — grounded-in-own-log ideation, the Phase-1+Phase-3 signature."
+
+  - prompt: "Prioritza idees de vídeo curt per aquesta setmana i digue'm quina gravem primer."
+    why: "Catalan for 'prioritize short-video ideas for this week and tell me which to film first' — generation + prioritization, core loop."
+
+should_not_trigger:
+  - prompt: "Write the shot-by-shot script and edit sheet for this Reel idea."
+    route_to: video-shorts
+    why: "Writing spoken lines and beat timecodes crosses out of ideation into the craft of one short."
+
+  - prompt: "What should our posting cadence and content pillars be?"
+    route_to: shortform-strategy
+    why: "Account-level positioning, pillars, and cadence are consumed by this skill, not authored by it."
+
+  - prompt: "Write the caption and pick the hashtags for this finished Reel."
+    route_to: shortform-packaging
+    why: "Caption/cover/hashtag-set for an already-shot cut is packaging; ideation only suggests a hashtag as a trend signal."
+
+  - prompt: "Give me YouTube video ideas with thumbnail-first packaging."
+    route_to: youtube-ideation
+    why: "YouTube's packaging-led, slower-decay idea pipeline is a different skill; this one is Reels/TikTok/Shorts-native."
+
+  - prompt: "Build us a metrics dashboard for our social performance."
+    route_to: analytics
+    why: "Generic reporting/dashboards live in analytics; this skill only reads the perf log to ground and score ideas."
+
+capability:
+  - scenario: "An account has a 2-month performance log in 02-DOCS where hook patterns A and B won (>60% 3s-hold) and topic C flopped twice. The user asks for next week's idea batch and to fold in this week's trending sounds."
+    must_include:
+      - "Reads/uses the 02-DOCS performance log to ground ideas (cites winning hooks A/B and the dead topic C; never re-pitches topic C)"
+      - "Captures at least one trend signal WITH a first-seen date and WITHOUT any scraping command (manual/assisted capture or sanctioned API)"
+      - "Produces a ranked backlog table with the required columns (id, idea, hook line, trend signal + date, format, target length, score, status)"
+      - "Scores each idea by hook strength and shareability/save (hook weighted highest), not by topic interest alone"
+      - "Writes at least one advanced idea as a dated hypothesis under 02-DOCS/shortform/experiments/ with result fields left pending"
+      - "Does NOT write full scripts or beat timecodes; explicitly hands the chosen idea off to video-shorts"

package/skills/shortform-ideation/references/experiment-ledger.md

@@ -0,0 +1,85 @@
+# Reference — the experiment ledger
+
+Phase 4 writes one file per advanced idea so the next ideation cycle learns from the
+last instead of re-guessing. The ledger lives under
+`02-DOCS/shortform/experiments/` and is read back in Phase 1.
+
+## File layout
+
+One markdown file per bet:
+
+```text
+02-DOCS/shortform/
+  performance.md                      # the running perf log (Phase 1 reads)
+  backlog.md                          # the ranked idea backlog (Phase 3 emits)
+  experiments/
+    2026-06-01-cafe-markup.md         # <YYYY-MM-DD>-<slug>.md, one per bet
+    2026-06-03-grind-myth.md
+```
+
+## Hypothesis record schema
+
+```markdown
+# SF-007 — "The €4 latte lie" cost breakdown
+
+- **id:** SF-007
+- **date:** 2026-06-01
+- **topic:** café pricing
+- **format:** faceless voiceover
+- **trend-signal:** voiceover-receipt format · TikTok→Reels early (<5k Reels) · first-seen 2026-06-01 · 7d↑
+- **hook-line:** pour shot + on-screen "your café charges 900% markup"
+- **target-length:** 18s
+- **score:** 45
+
+## Hypothesis
+Trend `voiceover-receipt` + hook `"900% markup"` will lift **3s-hold above 60%**
+for topic `café pricing` (vs our ~48% account baseline).
+
+## Result  <!-- fill after it runs -->
+- result: pending
+- posted-url: __
+- 3s-hold: __
+- hook-rate: __
+- shares: __
+- saves: __
+- watch-time/length: __
+- verdict: __   <!-- confirmed | falsified | inconclusive -->
+- learning: __  <!-- one line the next cycle inherits -->
+```
+
+**Rules:**
+
+- The **hypothesis is one falsifiable sentence** with a named metric and threshold.
+  "Will do well" is not a hypothesis; "will lift 3s-hold above 60%" is.
+- **Result fields ship as `pending`,** never omitted — an absent result field is how
+  a ledger silently rots. The structure must show the gap waiting to be filled.
+- The **trend-signal carries its first-seen date,** copied from Phase 2.
+
+## Worked before → after
+
+**Before (the bet, 2026-06-01):**
+
+> Hypothesis: `voiceover-receipt` + `"900% markup"` will lift 3s-hold above 60% for
+> café pricing. Result: pending.
+
+**After (filled 2026-06-05):**
+
+> 3s-hold: 71% · hook-rate: 34% · shares: 220 · saves: 480 · watch-time/length: 0.82
+> · verdict: **confirmed** · learning: *receipt/number hooks beat lifestyle hooks for
+> this account; promote `number-reveal` to a winning hook pattern in performance.md.*
+
+That `learning` line is the payload. In the next cycle's Phase 1, `number-reveal`
+now scores higher on **Hook strength** and **On-account fit**, and the ledger has
+done its only job: making the next batch smarter than the last.
+
+## CSV alternative
+
+If the account prefers one flat file over per-bet markdown, use
+`02-DOCS/shortform/experiments.csv` with columns:
+
+```text
+id,date,topic,format,trend_signal,trend_first_seen,hook_line,target_len,score,result,three_s_hold,hook_rate,shares,saves,verdict,learning
+```
+
+Same fields, same rule: a row is created at bet-time with `result=pending` and the
+result columns blank, then updated after the video runs.

package/skills/shortform-ideation/references/trend-sources.md

@@ -0,0 +1,69 @@
+# Reference — trend sources, the no-scrape rule, and freshness scoring
+
+Per-source capture recipes for Phase 2. Every signal you capture here carries a
+**first-seen date** before it is allowed into Phase 3 scoring. A signal with no
+date does not exist.
+
+## The hard rule: no scraping
+
+**TikTok Creative Center exposes no public trends API, and automated harvesting of
+it violates the ToS** — reinforced by the April 2026 rule updates. Do not write,
+suggest, or bake a scraper into any emitted artifact (no `curl`/`wget`/headless
+browser against `creativecenter` or `ads.tiktok.com`). Two sanctioned paths only:
+
+1. **Manual / assisted capture** — the user browses the surface and pastes the view
+   to you; you parse the pasted text.
+2. **Sanctioned API** — TikTok Research API or Commercial Content API on
+   `developers.tiktok.com`, with the user's own approved credentials.
+
+*Why:* a scraper is both a legal liability and a brittle dependency — the page
+structure changes, the loop breaks, and the account risks a ban.
+
+## Lane 1 — TikTok Creative Center
+
+- Trend Discovery (trending songs, hashtags, Top Ads) is browsable **in-app without
+  login** by switching the region to **United States**.
+- The data **refreshes every 24–48h** and lets you **compare 7-day vs 30-day
+  movement.** Always read both windows.
+- **Scoring rule:** a sound that moves only on the **30-day** view (flat or down on
+  7-day) is likely **dying** — mark `freshness: stale` and down-weight it. A sound
+  **rising on 7-day** is `peaking` or `early` — up-weight it.
+- Capture line: `sound/hashtag | TikTok-CC US | first-seen YYYY-MM-DD | 7d:↑/→/↓ | 30d:↑/→/↓`.
+
+## Lane 2 — Instagram trending audio
+
+- The native **Trending Audio list is gated to US Professional accounts.** A
+  trending sound shows an **upward-arrow indicator** next to its name in-app.
+- Non-US / non-pro accounts cannot see that list. Fall back to: the **Explore**
+  feed, **niche-creator repeat-use** (Lane 4), and **cross-platform origin tracking**
+  (Lane 3) — find what is breaking on TikTok/Shorts and watch it arrive on Reels.
+- Capture line: `audio | IG | first-seen YYYY-MM-DD | arrow:yes/no | source:explore/creator/cross-platform`.
+
+## Lane 3 — TikTok → Reels lead window
+
+- **Instagram Reels trends often lag TikTok by 3–7 days.** This lag is the
+  opportunity.
+- A sound **viral on TikTok** with **fewer than 5,000 Reels** using it on Instagram
+  is a documented **head-start window**. Mark it `freshness: early` and prioritize —
+  you arrive before saturation.
+- Capture line: `audio | TikTok→Reels | first-seen YYYY-MM-DD | reels-count:<5k | freshness:early`.
+
+## Lane 4 — Niche-creator repeat-use & templates
+
+- When **3+ creators in the account's niche** reuse the same sound/format/CapCut
+  template inside one week, treat it as **niche-validated** even before it shows on a
+  global trending list — niche relevance often beats global volume for a small account.
+- Scan CapCut "Trending" templates for the niche as a format (not just sound) signal.
+- Capture line: `format/template | niche-creators | first-seen YYYY-MM-DD | reuse-count:N`.
+
+## Freshness scoring summary
+
+| freshness | meaning | scoring action |
+|---|---|---|
+| `early` | TikTok-viral, <5k Reels, or 7d-rising and pre-peak | top weight — biggest head-start |
+| `peaking` | rising on both 7d and 30d, broadly visible | weight high but move fast |
+| `stale` | 30d-only movement, or first-seen >10 days ago | down-weight or drop; likely dying |
+
+A signal's freshness is recomputed each cycle from its **first-seen date** against
+today. Because Creative Center refreshes every 24–48h, a signal older than ~10 days
+with no fresh confirmation defaults to `stale`.