| name | ve-analyze |
| description | Stages 8–9 of the video-essay pipeline. After 24h since shorts publish, pull per-angle metrics from YouTube Shorts + Instagram Reels + TikTok, compute viral scores, pick a winner. Then user-approval checkpoint on whether to promote to long-form. Use when shorts are published ≥24h ago and shorts_metrics.json is absent or stale. |
ve-analyze — Stages 8–9
What this skill does
Pulls 24-hour metrics from the 3 platforms, computes a composite viral score per angle, flags the winner as strong or weak, and stops for a user decision on whether to promote to long-form. The algorithm picks the winner — no LLM judgment at this stage.
Stage 8: 24h wait + analysis
After 24 hours have passed since the LAST short was uploaded (check upload_result.json timestamps):
ve-analyze-shorts <slug>
This pulls metrics for each of the 3 published shorts:
- YouTube Shorts: views, avg view duration, avg % viewed (via Data API + Analytics API v2 — requires
yt-analytics.readonly scope)
- Instagram Reels: plays, sends, saves, avg watch time (via Upload-Post
GET /api/uploadposts/post-analytics/<request_id>)
- TikTok: plays, shares, avg watch time (same Upload-Post endpoint)
Computes a composite viral score per angle:
- 40% retention velocity
- 30% watch-time signal
- 20% unconnected reach
- 10% absolute views
Weighting is derived from references/shorts_bible.md Part 5 priority order. All three platforms contribute; retention is averaged across whichever platforms returned data.
Writes $EPISODES_DIR/<slug>/shorts_metrics.json with per-angle scores, ranking, and a decision block naming the winner.
Stage 9: Winner promotion decision
ve-analyze-shorts always picks the highest-scoring angle. The decision block flags it as:
strong_winner — score > 0.6 AND views > 500. Normal case. Promote with confidence.weak_winner — best of 3 but below thresholds. Pipeline still promotes (always-promote policy, locked 2026-04-15), but a warning surfaces for the user.
Checkpoint: present shorts_metrics.json to the user — full table of per-angle scores, the winner, and the strong/weak flag. User confirms one of:
- "promote A to long-form" — proceed. Update
packages.md with winner: A and hand off to ve-longform.
- "kill the topic, pick a new one for episode <NNN+1>" — stop. No long-form. User restarts with
ve-intake on a new topic.
- "promote B instead, I think the metric was confounded" — manual override. Update
packages.md with winner: B, note the override reason in the decision block, proceed.
Handoff
On promote decision → ve-longform (Stage 10). On kill → stop; the pipeline for this slug is done. No long-form is produced.
