rsc-universal 0.1.1

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

@@ -0,0 +1,210 @@
+#!/usr/bin/env bash
+#
+# verify.sh — structural guardrail for an emitted short-form package file.
+#
+# WHAT IT DOES (read-only; never edits, writes, or hits the network)
+#   Static lint over ONE package draft you point it at. The draft is plain text /
+#   markdown with labeled sections. Recognized labels (any case, English or ES/CA),
+#   one per line; list items are lines starting with "-". Recognized labels:
+#     Hook:        hook / gancho / ganxo            (one variant per "- " line)
+#     On-screen:   on-screen text / texto en pantalla / text en pantalla / overlay
+#     Caption:     caption / pie de foto / descripcion / descripció / peu de foto
+#     Hashtags:    hashtags
+#     Cover:       cover / portada
+#     Feedback:    feedback
+#
+#   Checks (only present-but-broken sections FAIL; empty file is clean):
+#     1. Hook: >= 2 variants                         -> FAIL if < 2.
+#     2. On-screen text: present, each line <= 7 words -> FAIL per over-long line.
+#     3. Caption: first non-empty line <= 150 chars
+#        and does NOT open with a banned teaser
+#        ("wait for it", "in this video",
+#         "you won't believe", "watch till the end") -> FAIL.
+#     4. Hashtags: count between 3 and 5 inclusive    -> FAIL if <3 or >5.
+#     5. Cover: a frame + an overlay line present     -> FAIL if missing.
+#     6. Feedback: block has intro_retention,
+#        sends_per_reach, saves                       -> FAIL per missing key;
+#        warn if "likes" is logged as a metric.
+#
+#   A clean OR empty/whitespace-only file exits 0 — never a false failure.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh package.md            # run all checks
+#   ./verify.sh package.md --strict   # treat warnings as failures (CI gate)
+#
+# EXIT CODES
+#   0  clean, warnings only (without --strict), or empty/missing-content file
+#   1  a hard failure — or any warning under --strict
+#   2  bad usage (no file given, or file does not exist)
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays, no bc.
+
+set -u
+
+FAIL=0
+WARN=0
+STRICT=0
+FILE=""
+
+for arg in "$@"; do
+  case "$arg" in
+    --strict) STRICT=1 ;;
+    -*) echo "usage: verify.sh <package-file> [--strict]" >&2; exit 2 ;;
+    *) FILE="$arg" ;;
+  esac
+done
+
+if [ -z "$FILE" ]; then
+  echo "usage: verify.sh <package-file> [--strict]" >&2
+  exit 2
+fi
+if [ ! -f "$FILE" ]; then
+  echo "verify.sh: file not found: $FILE" >&2
+  exit 2
+fi
+
+fail() { echo "FAIL: $1"; FAIL=$((FAIL + 1)); }
+warn() { echo "WARN: $1"; WARN=$((WARN + 1)); }
+
+# Empty / whitespace-only file is clean — never a false failure.
+if ! grep -q '[^[:space:]]' "$FILE"; then
+  echo "OK: empty file, nothing to lint."
+  exit 0
+fi
+
+# --- helpers ---------------------------------------------------------------
+# Lower-case a string (bash 3.2 has no ${x,,}).
+lc() { printf '%s' "$1" | tr '[:upper:]' '[:lower:]'; }
+
+# Extract the list-item lines ("- ...") belonging to a section, by label regex.
+# Section ends at the next non-indented label line or EOF.
+section_items() { # $1 = label-regex
+  awk -v re="$1" '
+    BEGIN { inb = 0 }
+    {
+      line = $0
+      low = tolower(line)
+      # A label line: starts at column 0 (no indent), letters then a colon.
+      if (line ~ /^[^[:space:]].*:/) {
+        inb = (low ~ re) ? 1 : 0
+        next
+      }
+      if (inb && line ~ /^[[:space:]]*-[[:space:]]*/) {
+        sub(/^[[:space:]]*-[[:space:]]*/, "", line)
+        if (line ~ /[^[:space:]]/) print line
+      }
+    }
+  ' "$FILE"
+}
+
+# Raw body lines of a section (non-list, e.g. caption / cover / feedback).
+section_body() { # $1 = label-regex
+  awk -v re="$1" '
+    BEGIN { inb = 0 }
+    {
+      line = $0
+      low = tolower(line)
+      if (line ~ /^[^[:space:]].*:/) {
+        if (low ~ re) { inb = 1; next }
+        inb = 0; next
+      }
+      if (inb && line ~ /[^[:space:]]/) print line
+    }
+  ' "$FILE"
+}
+
+# --- 1. Hook: >= 2 variants -----------------------------------------------
+HOOK_RE='^(hook|gancho|ganxo) *:'
+hook_count=$(section_items "$HOOK_RE" | grep -c '.')
+if [ "$hook_count" -ge 1 ]; then
+  if [ "$hook_count" -lt 2 ]; then
+    fail "Hook: ship a SET — found $hook_count variant(s), need >= 2."
+  fi
+else
+  warn "Hook section not found (label 'Hook:'); skipping hook check."
+fi
+
+# --- 2. On-screen text: present, each <= 7 words --------------------------
+OS_RE='^(on-screen text|on-screen|texto en pantalla|text en pantalla|overlay) *:'
+os_items=$(section_items "$OS_RE")
+if [ -n "$os_items" ]; then
+  printf '%s\n' "$os_items" | while IFS= read -r ln; do
+    [ -z "$ln" ] && continue
+    w=$(printf '%s\n' "$ln" | wc -w | tr -d ' ')
+    if [ "$w" -gt 7 ]; then
+      echo "FAIL: On-screen text over 7 words ($w): $ln"
+    fi
+  done
+  # re-count failures from the subshell via a marker grep
+  os_fails=$(printf '%s\n' "$os_items" | awk '{ if (NF>7) c++ } END { print c+0 }')
+  FAIL=$((FAIL + os_fails))
+else
+  warn "On-screen text section not found; skipping word-count check."
+fi
+
+# --- 3. Caption: first line <= 150 chars, no banned teaser ----------------
+CAP_RE='^(caption|pie de foto|peu de foto|descripcion|descripció) *:'
+cap_first=$(section_body "$CAP_RE" | grep -m1 '[^[:space:]]')
+if [ -n "$cap_first" ]; then
+  cap_trim=$(printf '%s' "$cap_first" | sed 's/^[[:space:]]*//')
+  len=$(printf '%s' "$cap_trim" | wc -c | tr -d ' ')
+  if [ "$len" -gt 150 ]; then
+    fail "Caption first line is $len chars (> 150 visible budget)."
+  fi
+  cap_lc=$(lc "$cap_trim")
+  for bad in "wait for it" "in this video" "you won't believe" "watch till the end"; do
+    case "$cap_lc" in
+      "$bad"*) fail "Caption opens with banned teaser: \"$bad\". Lead with the keyword." ;;
+    esac
+  done
+else
+  warn "Caption section not found; skipping caption checks."
+fi
+
+# --- 4. Hashtags: 3-5 inclusive -------------------------------------------
+HT_RE='^hashtags *:'
+ht_body=$(section_body "$HT_RE")
+if [ -n "$ht_body" ]; then
+  ht_count=$(printf '%s\n' "$ht_body" | grep -o '#[[:alnum:]_]\{1,\}' | grep -c '.')
+  if [ "$ht_count" -lt 3 ] || [ "$ht_count" -gt 5 ]; then
+    fail "Hashtags: found $ht_count — use 3-5 (Instagram hard-caps at 5)."
+  fi
+else
+  warn "Hashtags section not found; skipping count check."
+fi
+
+# --- 5. Cover: frame + overlay present ------------------------------------
+COV_RE='^(cover|portada) *:'
+cov_body=$(section_body "$COV_RE")
+if [ -n "$cov_body" ]; then
+  cov_lc=$(lc "$cov_body")
+  printf '%s' "$cov_lc" | grep -q 'frame' || fail "Cover: no 'frame:' specified."
+  printf '%s' "$cov_lc" | grep -q 'overlay' || fail "Cover: no 'overlay:' line specified."
+else
+  warn "Cover section not found; skipping cover check."
+fi
+
+# --- 6. Feedback block: required keys -------------------------------------
+FB_RE='^feedback *:'
+fb_body=$(section_body "$FB_RE")
+if [ -n "$fb_body" ]; then
+  fb_lc=$(lc "$fb_body")
+  for key in intro_retention sends_per_reach saves; do
+    printf '%s' "$fb_lc" | grep -q "$key" || fail "Feedback block missing key: $key."
+  done
+  if printf '%s' "$fb_lc" | grep -Eq '^[[:space:]]*likes[[:space:]]*:'; then
+    warn "Feedback logs 'likes' as a metric — track intro_retention/sends/saves instead."
+  fi
+else
+  warn "Feedback section not found; skipping key check."
+fi
+
+# --- verdict ---------------------------------------------------------------
+echo "----"
+echo "checks done: $FAIL failure(s), $WARN warning(s)."
+if [ "$FAIL" -gt 0 ]; then exit 1; fi
+if [ "$STRICT" -eq 1 ] && [ "$WARN" -gt 0 ]; then
+  echo "strict mode: warnings treated as failures."
+  exit 1
+fi
+exit 0

package/skills/shortform-strategy/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: shortform-strategy
+description: "Use when running the durable strategy layer of a TikTok and/or Instagram Reels account — positioning, posting cadence, format mix, which trends and sounds to ride, recurring series, and the what-worked learning loop — not making one video. Use for standing up a new account before posting; diagnosing a flat or declining account (positioning, cadence, or format?); deciding whether to ride a trend or sound now; designing a recurring series; the monthly strategy review; or choosing the Reels-vs-carousel mix. Triggers: 'starting a new TikTok account, what and how often should we post', 'we post every single day and our reach is going down' (cadence-dilution symptom, no strategy word), 'should we jump on this sound or is it dead', 'we want a weekly recurring series on Reels', 'muntar l''estratègia del compte de Reels: posicionament i cadència', '¿nos subimos a esta tendencia o ya pasó?'. NOT writing the single short script or hook variants (that is video-shorts)."
+tags: [short-form-video, tiktok, instagram-reels, account-growth, positioning, posting-cadence, trends, series, algorithm-2026]
+recommends: [video-shorts, shortform-ideation, shortform-packaging, shortform-editing, social-publisher, content-engine, brand-voice, analytics]
+origin: risco
+---
+
+# Shortform Strategy — The Account Operating System
+
+*You own the account, not the clip.* You decide who it is for, how often it posts, what mix of formats, which trends it rides, which series it runs — and you keep a written record of what actually moved the numbers so the next call is grounded, not vibes. You produce a **strategy doc**, a **posting plan**, and a **decision log**. You never write the script, the cover, the caption, or the cut.
+
+Hand off downstream the moment the deliverable becomes *one video*:
+- The 15–60s script and hook variants → `../video-shorts/SKILL.md`.
+- The topic/angle backlog feeding the account → **shortform-ideation**.
+- The cover frame / on-screen title / first-frame packaging → **shortform-packaging**.
+- The cut, caption burn-in, sound sync → **shortform-editing**.
+- Cross-platform calendar/scheduler across X/LinkedIn/Threads → `../social-publisher/SKILL.md`.
+- The top-down editorial system across all content types → `../content-engine/SKILL.md`.
+- The durable tone the account speaks in → `../brand-voice/SKILL.md`.
+
+**Boundary test:** if it is one asset, route it. If it is *what the whole account does, on what rhythm, and the record of what worked* — it is yours.
+
+## Step 0 — Read the ledger before you decide anything
+
+Strategy without memory is just opinion. Before any call, read what the account already learned:
+
+- `02-DOCS/wiki/shortform/` — the compiled strategy, positioning, and dated decisions.
+- `02-DOCS/raw/shortform/` — the per-post metrics ledger (completion %, sends, saves, follows).
+
+*Why: the account is a feedback loop. If you cannot point to the prior decision and the metric that backs it, you are guessing — and you will re-make a mistake the ledger already recorded.* If the directories are empty, this is a new account: say so explicitly and create the baseline in Step 0's write-back, then proceed to Positioning.
+
+The numbers below age fast. The dated, sourced cheat-sheet lives in `references/platform-signals-2026.md` — cite it, do not re-derive it.
+
+## Positioning — the one promise and the lane
+
+An account grows when a stranger can finish your video and instantly know *what they get if they follow*. Vague accounts do not grow; specific lanes do — "productivity for remote workers", "true crime in 5 minutes" — because the algorithm rewards retention and a tight lane is what holds a cohort to the end (almcorp.com short-form mastery 2026; virvid.ai faceless 2026 — accessed 2026-06-02).
+
+Write the positioning as one sentence: **`<for whom>` gets `<one promise>` in `<format/lane>`.** If you cannot, the account has no lane yet — narrow before you post.
+
+Faceless is fine. Retention, not a face, is what the algorithm scores. A faceless account is viable *if the retention holds*; if it does not, the problem is the lane or the hook, never the missing face.
+
+| Signal | Diagnosis | Move |
+|---|---|---|
+| Clear one-promise sentence + completion holding | Lane is working | Proceed to cadence |
+| Sentence is fuzzy / lists 3+ niches | No lane — this is the growth blocker | Narrow to ONE promise, re-test 2 weeks |
+| Clear lane but completion < niche bar | Lane fine, execution weak | Fix hook/length (hand to `../video-shorts/SKILL.md`), not the lane |
+| Faceless, retention proven | Viable | Keep faceless; do not chase a face |
+
+## Cadence and mix — consistency beats velocity
+
+Pick the rhythm the account can *sustain*. Consistency now outperforms sporadic viral hits, and posting past the ceiling dilutes quality and burns the operator out (automateed.com; truescho.com; newzenler.com — accessed 2026-06-02).
+
+| Account / platform | Cadence | Why |
+|---|---|---|
+| TikTok | 3–5 quality posts/week | Consistency sweet spot; daily-but-thin loses to fewer-but-sharper |
+| Instagram Reels | 4–7 Reels/week | Reach-vs-engagement optimum |
+| Instagram full mix (weekly) | 3–4 Reels + 2–3 carousels + 1–2 statics | Reels drive growth; carousels drive depth |
+| Any platform | Hard ceiling ~10/week | Past this: diminishing returns + burnout + quality dilution |
+
+**Format mix rule (Instagram):** carousels now average ~10% engagement vs ~6% for regular Reels and get a "second chance" surge of 2–3× impressions — but **for small accounts Reels remain the biggest visibility driver** (thesecondbrain.io; reelbase.io; usevisuals.com — accessed 2026-06-02). So: lean Reels for *growth*, carousels for *sales/community*. Do not pile into carousels on a small account chasing the engagement headline — you will trade reach you need for engagement you do not yet.
+
+Bad → Good:
+- Bad: "We'll post twice a day to grow faster."
+- Good: "4 Reels/week we can actually make well, same two days each week, for 4 weeks; we raise volume only if completion holds."
+
+## Hook-first at the account level
+
+Make the account's KPI **first-3s retention and completion %**, not views or likes. The first 3 seconds decide a Reel, and watch-time/completion is the strongest retention signal — a fully-watched 15s beats a 60s most people abandon (truefuturemedia.com; buffer.com — accessed 2026-06-02). On TikTok the 2026 bar rose: ~70%+ completion to go viral (up from ~50% in 2024), and an 85% completion threshold trips a ~4× distribution multiplier (socialboostdigital.com; socialync.io — accessed 2026-06-02).
+
+Set length bands as account policy, then let depth get scripted downstream:
+
+| Goal | Length band | Why |
+|---|---|---|
+| New-audience reach + completion | 7–30s | Easiest to fully watch; clears the completion bar |
+| Depth with existing followers | 30–90s | Room to teach; full 7–90s is the highest-viral band |
+
+You set the band and the KPI. The actual hook and per-second pacing is `../video-shorts/SKILL.md`'s job — point to it, do not write it here.
+
+## Trends and sounds — the ride-or-skip call
+
+In 2026 a trending sound is a **niche/category signal, not a raw boost**. Using a sound trending *within your niche* nudges TikTok to drop your test cohort into that niche (which raises completion); the 2022–2024 direct distribution boost is gone. Adopt within ~24h of it trending or skip it (sproutsocial.com; opus.pro — accessed 2026-06-02).
+
+Run the call as a gate — all three must be yes to ride:
+
+```text
+1. Is the sound/trend trending WITHIN our niche (not just globally)?   no -> SKIP
+2. Is it < ~24h old (still on the rising edge)?                        no -> SKIP
+3. Does the format fit our positioning without contorting it?         no -> SKIP
+all yes -> RIDE: ship within 24h, treat the first ~30 minutes as the test
+```
+
+Why the 30-minute window matters: "view velocity" — engagement inside roughly the first 30 minutes of distribution — is a dominant early signal in 2026 (socialboostdigital.com; socialync.io — accessed 2026-06-02). A trend you publish late, off-niche, or twisted to fit gives you all the production cost and none of the cohort lift. When in doubt, **skip** — a missed trend costs nothing; a forced one costs a slot and muddies your lane.
+
+## Series — the compounding move
+
+Multi-part series drive roughly **2.8× higher return viewers** because a recurring format builds the habit the algorithm rewards (socialboostdigital.com; socialync.io — accessed 2026-06-02). A series is the cheapest durable lift you can design.
+
+Design it as a *contract with the viewer*:
+- **Name + number it** — "Tiny Systems #07" — so a returning viewer recognizes it in the first frame.
+- **Fix a cadence** — same slot, same rhythm (e.g. every Tuesday). A series with no schedule is just a hashtag.
+- **Pilot before committing.** Use **Trial Reels** (public IG accounts, 1,000+ followers, available since July 2025) to publish the pilot to non-followers first and read the signal before showing your existing audience — a built-in A/B surface for a format bet (later.com; socialpilot.co — accessed 2026-06-02).
+
+The hand-off: you define the series *concept, cadence, and numbering*. The episodes get ideated (shortform-ideation), scripted (`../video-shorts/SKILL.md`), and packaged (shortform-packaging) elsewhere.
+
+## The learning loop — log, review, write back
+
+Every decision must end up in the ledger so next month's call is grounded.
+
+**Log per post** (not just likes): date, platform, format, hook, length, sound, **completion %**, **sends**, **saves**, follows, notes. DM sends are the top distribution signal for Reels in 2026 — share-via-DM carries the most weight for unconnected reach, and shares/saves outrank likes (later.com; truefuturemedia.com; mirra.my — accessed 2026-06-02). If you only log likes and views, you are blind to the signal that actually moves reach.
+
+**Monthly review ritual:** read the ledger, find the top-3 and bottom-3 by completion and by sends, name the pattern, make one positioning/cadence/series change, and record it as a dated decision. The full per-post schema, review checklist, and decision-record template live in `references/learning-loop-template.md` — use it verbatim so the ledger stays machine-readable.
+
+### Decision record format
+
+Append every call to `02-DOCS/wiki/shortform/decisions.md` as a dated block:
+
+```markdown
+## 2026-06-02 — Drop daily posting to 4 Reels/week
+**Decision:** Cut from ~7 thin posts/week to 4 strong Reels/week, fixed Tue/Fri.
+**Rationale:** Reach fell as volume rose; consistency > velocity past the ceiling.
+**Rests on:** completion avg 31% (ledger), cadence-ceiling signal (platform-signals-2026).
+**Revisit on:** 2026-07-02 — keep if completion clears 40% and sends/post rise.
+```
+
+*Why dated + rests-on + revisit: a decision you cannot trace to a metric and a date is folklore. The revisit line turns it into an experiment with an end.*
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| Riding a trend after it peaked / off-niche | Sound is a niche signal now, not a boost; late + off-niche = cost, no lift | Run the 3-gate ride-or-skip; ship within 24h or skip |
+| Cross-posting identical creative everywhere | An Originality Score suppresses recycled/reposted content | Re-cut natively per platform; treat each as original |
+| Posting 10+/week to "grow faster" | Diminishing returns + burnout + quality dilution | Hold 3–5 (TikTok) / 4–7 (Reels); raise only if completion holds |
+| Optimizing likes/views | Sends/saves/completion are what move reach; likes are vanity | KPI = completion % + sends/saves; log them per post |
+| No clear lane ("a bit of everything") | Algorithm rewards retention; a fuzzy lane never holds a cohort | One-promise sentence first; narrow before posting |
+| Hashtag-spamming for discovery | Discovery shifted to keywords; hashtags no longer support follows | Keywords in caption/profile/on-screen text; drop the hashtag wall |
+| "Series" with no fixed schedule | No habit forms; it is just a tag, no return-viewer lift | Name + number + fixed slot; pilot via Trial Reels |
+| Deciding from vibes, not the ledger | Re-makes recorded mistakes; nothing compounds | Read `02-DOCS/...` first; every call gets a dated decision record |
+
+## Persist it
+
+Write the account's brain back so it compounds (mirrors the harness Karpathy-wiki convention):
+
+- `02-DOCS/wiki/shortform/strategy.md` — positioning, cadence/mix, KPI, length bands, current series.
+- `02-DOCS/wiki/shortform/decisions.md` — the dated decision log (format above).
+- `02-DOCS/raw/shortform/metrics.csv` — the per-post ledger (schema in `references/learning-loop-template.md`).
+
+Verify a produced strategy doc with `scripts/verify.sh 02-DOCS/wiki/shortform/strategy.md` — a read-only structural lint (positioning, cadence, completion KPI, ride-or-skip rule, ≥1 dated decision, sends/saves logged).

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

@@ -0,0 +1,3 @@
+# Evals — shortform-strategy
+
+These are routing and capability cases for manual or harness-driven evaluation; there is no automated runner. To run them, prompt the model (with this skill available) using each `should_trigger` prompt and confirm the skill activates, then each `should_not_trigger` prompt and confirm it routes to the named sibling instead. For the `capability` case, give the model the scenario, let it produce a full strategy, and grade the output against the `must_include` rubric — every bullet should be satisfiable from the produced strategy doc + decision log. The `scripts/verify.sh` linter checks the *structure* of a produced strategy doc but not these routing/capability judgments, which stay human-graded.

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

@@ -0,0 +1,52 @@
+skill: shortform-strategy
+
+should_trigger:
+  - prompt: "Starting a new TikTok account for my bakery — what should we post and how often?"
+    why: New-account positioning + cadence plan before posting anything; the core job.
+  - prompt: "Our Reels reach has been dropping even though we post every single day."
+    why: Non-obvious cadence-dilution symptom with no strategy keyword — diagnosing positioning vs cadence vs format is exactly this skill.
+  - prompt: "Is it worth jumping on this trending sound or has it already peaked?"
+    why: The ride-or-skip trend/sound call (niche-relevance + <24h age gate).
+  - prompt: "We want a recurring weekly series on our Reels to bring people back."
+    why: Series design for return viewers (~2.8× lift); cadence + numbering + Trial Reels pilot.
+  - prompt: "Muntar l'estratègia del compte de Reels: posicionament i cadència."
+    why: Catalan; account-level positioning + cadence — the strategy layer, not one asset.
+  - prompt: "Monthly review of our TikTok — what worked last month and what do we change?"
+    why: The learning-loop review ritual — read the ledger, name the pattern, make one dated decision.
+  - prompt: "Should we lean Reels or carousels on our small Instagram account?"
+    why: Format-mix decision (growth vs sales/community) at the account level.
+
+should_not_trigger:
+  - prompt: "Write me a 30-second Reel script with 5 hook variants."
+    route_to: video-shorts
+    why: Single-asset scripting and hook variants, not account strategy.
+  - prompt: "Give me 20 video ideas for my fitness TikTok."
+    route_to: shortform-ideation
+    why: Idea/angle backlog generation, not positioning/cadence/series.
+  - prompt: "Design the cover frame and on-screen title for this Reel."
+    route_to: shortform-packaging
+    why: Packaging of one piece (cover/title/first-frame), not the account OS.
+  - prompt: "Cut this footage and burn in captions synced to the beat."
+    route_to: shortform-editing
+    why: The edit — cuts, captions, sound sync — not strategy.
+  - prompt: "Build a posting calendar across LinkedIn, X and Threads with char limits."
+    route_to: social-publisher
+    why: Cross-platform scheduling/calendar with char limits, not the shortform account strategy.
+  - prompt: "Define our brand voice and tone of voice."
+    route_to: brand-voice
+    why: Durable tone the account speaks in, not what/when it posts.
+
+capability:
+  - scenario: >
+      A flat faceless productivity TikTok+Reels account, posting daily across
+      mixed niches, running no series, and tracking only likes and views.
+      Produce a strategy.
+    must_include:
+      - "Reads 02-DOCS/wiki/shortform + 02-DOCS/raw/shortform first (Step 0), then writes the strategy/decision/ledger back."
+      - "Diagnoses positioning: mixed niches = no lane; narrows to one one-promise sentence."
+      - "Corrects cadence to 3–5 (TikTok) / 4–7 (Reels) and flags the daily-posting dilution / ceiling."
+      - "Sets completion % and sends/saves as the KPI, explicitly over likes/views."
+      - "Gives a ride-or-skip trend/sound rule (niche-relevance + <24h + on-positioning gate)."
+      - "Proposes a named, numbered, scheduled recurring series; suggests piloting via Trial Reels."
+      - "Writes at least one dated decision record (date, decision, rests-on metric, revisit-on)."
+      - "Cites the format mix (Reels for growth / carousels for community) and the 7–30s vs 30–90s length bands."

package/skills/shortform-strategy/references/learning-loop-template.md

@@ -0,0 +1,49 @@
+# Learning-loop template
+
+The forms that keep SKILL.md a playbook instead of a worksheet. Copy these verbatim into the project so the ledger stays machine-readable and decisions stay traceable.
+
+## Per-post metrics ledger
+
+Write to `02-DOCS/raw/shortform/metrics.csv`. One row per published post. The non-vanity columns — `completion_pct`, `sends`, `saves` — are the ones that drive reach in 2026; logging only `likes`/`views` makes you blind to the actual signal.
+
+```csv
+date,platform,format,hook,length_s,sound,completion_pct,sends,saves,follows,notes
+2026-06-02,tiktok,reel,"3 tabs every remote worker should close",18,trending-niche,68,42,77,9,"series #07; rode niche sound <24h"
+2026-06-04,instagram,carousel,"the 4pm energy crash fix",,,,31,120,4,"sales angle; saves high, sends low"
+```
+
+Column notes:
+- `format`: `reel` | `carousel` | `static` | `tiktok`.
+- `length_s`: blank for non-video (carousel/static).
+- `sound`: `trending-niche` | `trending-global` | `original` | blank.
+- `completion_pct`: integer percent; the account's primary KPI.
+- `sends`: DM-shares (top Reels distribution signal in 2026).
+- `saves`: outrank likes; depth/intent signal.
+- `notes`: series tag, trend call, anything to read next month.
+
+Deliberately **no `likes` column** — if you want it, add it last, never first.
+
+## Monthly review checklist
+
+Run once a month, reading `02-DOCS/raw/shortform/metrics.csv`:
+
+- [ ] Sort by `completion_pct`: name the top 3 and bottom 3 posts. What do the top 3 share?
+- [ ] Sort by `sends`: same — which hooks/formats earned shares?
+- [ ] Compare actual cadence to the planned cadence (3–5 TikTok / 4–7 Reels). Over the ceiling?
+- [ ] Did any series episode beat the account average? Keep, kill, or re-pilot it.
+- [ ] Which trend calls paid off (rode within 24h, on-niche) vs which were forced?
+- [ ] Make exactly **one** change to positioning, cadence, mix, or series — not five.
+- [ ] Record it as a dated decision (template below). Set a `revisit on` date.
+- [ ] Write the compiled state back to `02-DOCS/wiki/shortform/strategy.md`.
+
+## Decision-record template
+
+Append to `02-DOCS/wiki/shortform/decisions.md`. Every block is dated, rests on a named metric, and carries a revisit date so it is an experiment, not folklore.
+
+```markdown
+## YYYY-MM-DD — <short decision title>
+**Decision:** <what changes, concretely — cadence/positioning/series/trend rule>
+**Rationale:** <the one-line why>
+**Rests on:** <ledger metric(s) + which platform signal, e.g. completion avg 31%, cadence ceiling>
+**Revisit on:** YYYY-MM-DD — <the condition that confirms or reverses this>
+```

package/skills/shortform-strategy/references/platform-signals-2026.md

@@ -0,0 +1,46 @@
+# Platform signals — 2026 cheat-sheet
+
+One citable home for the numbers that age fast. SKILL.md references this instead of scattering figures. Every line is dated (accessed **2026-06-02**) and sourced. Re-verify before relying on any of these past Q3 2026 — algorithm signals move quarterly.
+
+## Distribution signals
+
+| Signal | 2026 state | Source |
+|---|---|---|
+| Reels top distribution trigger | **Share-via-DM to a friend** carries the most weight for unconnected (non-follower) reach; shares/saves outrank likes; DM-sends moved from a secondary 2025 signal to the *primary* trigger | later.com "Instagram algorithm in 2026"; truefuturemedia.com Reels Reach 2026; mirra.my Instagram Algorithm 2026 |
+| Retention | First **3 seconds** decide a Reel; watch-time/completion is the strongest retention signal — a fully-watched 15s beats a 60s most abandon | truefuturemedia.com; buffer.com Instagram Algorithm 2026 |
+| TikTok completion bar | ~**70%+** completion to go viral (up from ~50% in 2024); **85%** completion trips a ~**4×** distribution multiplier | socialboostdigital.com; socialync.io TikTok Algorithm Changes 2026 |
+| View velocity | Engagement inside roughly the **first ~30 minutes** of distribution is a dominant early signal | socialboostdigital.com; socialync.io |
+| Discovery | Shifted from **hashtags to keywords** (caption/profile/on-screen text); hashtags no longer support follows; an **Originality Score** suppresses recycled/reposted content | truefuturemedia.com; creatorflow.so Instagram Algorithm 2026 |
+
+## Length bands
+
+| Goal | Band | Source |
+|---|---|---|
+| New-audience reach + completion | **7–30s** | socialpilot.co; syncstudio.ai Reels Algorithm 2026 |
+| Depth with existing followers | **30–90s** | socialpilot.co; syncstudio.ai |
+| Highest-viral band overall | **7–90s** | socialpilot.co; syncstudio.ai |
+
+## Cadence and mix
+
+| Item | 2026 figure | Source |
+|---|---|---|
+| TikTok consistency sweet spot | **3–5** quality posts/week | automateed.com; truescho.com; newzenler.com |
+| Reels reach-vs-engagement optimum | **4–7** Reels/week | automateed.com; newzenler.com |
+| Ceiling | **10+/week** → diminishing returns + burnout + dilution | automateed.com; truescho.com |
+| Instagram weekly mix optimum | ~**3–4 Reels + 2–3 carousels + 1–2 statics** | thesecondbrain.io; reelbase.io; usevisuals.com |
+| Carousel vs Reel engagement | Carousels ~**10%** avg vs ~**6%** for regular Reels; carousels get a 2–3× "second chance" impressions surge | thesecondbrain.io; usevisuals.com |
+| Small-account caveat | **Reels remain the biggest visibility driver** for small accounts; lean Reels for growth, carousels for sales/community | reelbase.io; usevisuals.com |
+
+## Trends, sounds, series
+
+| Item | 2026 state | Source |
+|---|---|---|
+| Trending sounds | A **niche/category signal, not a raw boost** — a sound trending *within your niche* nudges TikTok to place your test cohort in that niche (raising completion); the 2022–2024 direct boost is gone. Adopt within **~24h** of trending | sproutsocial.com; opus.pro TikTok new algorithm 2026 |
+| Series | Multi-part series drive ~**2.8×** higher return viewers; recurring formats build the habit the algorithm rewards | socialboostdigital.com; socialync.io |
+| Trial Reels | Public IG accounts, **1,000+ followers**, since **July 2025** — publish to non-followers first to gather signal before showing existing audience; a built-in A/B surface for positioning/format bets | later.com; socialpilot.co |
+
+## Positioning
+
+| Item | 2026 state | Source |
+|---|---|---|
+| Niche lane | Specific lanes ("productivity for remote workers", "true crime in 5 minutes") grow; vague accounts do not. The algorithm rewards retention, so **faceless is viable if retention holds** | almcorp.com short-form mastery 2026; virvid.ai faceless 2026 |