--- name: remotion-video description: Use when the user wants to generate a rendered promotional video (not just a script) for a PR, feature, or product change — produces a Remotion project, iterates with preview, and outputs mp4 + poster for X/LinkedIn/social. ---

# Remotion Video

Turn a PR into a rendered short-form promo video with a hook, code moments, and CTA, using Remotion. Iterate with live preview in Remotion Studio, then render `video.mp4` and `poster.jpg` for X/LinkedIn/social.

Unlike `/video-script` (which produces a textual script), this skill produces the actual video file.

## Triggers

Invoke when the user says: "make a video for this PR", "remotion video", "render a promo video", "video for X/LinkedIn", or when selected from `/marketing-pipeline`.

## Process Flow

``` Resolve input → Phase 1: Discovery → Phase 2: Configuration → Phase 3: Narrative planning → Phase 4: Scaffold → Phase 5: First draft + iterate → Phase 6: Render → Phase 7: Cleanup ```

Phases 1, 3, 5, and 7 have explicit approval gates. Phase 2 is an interactive Q&A. Phase 5 is a freeform iteration loop that can run many rounds.

## "Use Sane Defaults" / "Don't Ask Questions" — What It Does and Doesn't Override

When the user invokes the skill with phrasing like *"use sane defaults"*, *"don't ask questions"*, *"non-interactive"*, *"just ship it"*, or any equivalent — interpret it precisely:

**It DOES override (skip the prompt, pick the default):**

- Q2.1 duration → derive from scope using the ladder in Q2.1 (still in the 15–60s window); pick the midpoint of the matched scope band and proceed without asking - Q2.2 aspect ratio → 16:9 landscape - Q2.3 project location → `marketing/<feature-slug>/remotion/` - Q2.4 brand *confirmation* (the "use these / customize / provide your own?" question) - Phase 1.4 scope confirmation - Phase 3.0 motif confirmation - Phase 3.1 story-pattern confirmation - Phase 3.3 scene-plan approval - Phase 5 freeform iteration loop (the "what would you like to change?" prompt)

**It does NOT override (must always run regardless):**

- Brand color/font/logo **scanning** (Q2.4 detection — see HARD-GATE in Q2.4). Hardcoding colors from training-data assumptions about a project is a forbidden shortcut. - Phase 5 **preview** (Remotion Studio must start and the studio URL must be opened in the browser before the render runs). Even in fully unattended mode, the user can interrupt; the agent must not pre-decide for them. - Phase 6 pre-render audits (storytelling, hook rules, motif presence, pacing variance, value-prop timing, contrast). These exist to prevent shipping a generic video. - Phase 7 cleanup question (the user owns project disposition).

If you're tempted to skip a HARD-GATE because the user "said no questions" — re-read this section. The user said no *questions*, not no *gates*.

## Input Resolution

Resolve the argument (if provided) in this order:

1. Path to a marketing brief (`.md` containing "Executive Summary" or "Key Messages") → **marketing brief** 2. Path to a blog post (`.md` with blog post structure) → **blog post** 3. Path to a changelog → **changelog** 4. GitHub PR URL or `#\d+` pattern → **PR** 5. Matches `<ref>..<ref>` or `<ref>...<ref>` (alphanumeric + `/`, `_`, `.`, `-` on each side) → **git ref range** 6. Resolves to an existing file/directory → **codebase feature** 7. Otherwise → **freeform text**

If no argument is provided, ask: "What should the video be about? You can provide a PR URL/number, marketing brief, blog post, changelog, git ref range, file/directory path, or just describe the feature."

When invoked from the pipeline with a PR *and* upstream marketing-brief/blog-post paths, read both: PR for technical accuracy, upstream content for positioning/tone.

(Detailed phase specs begin below — see Phase 1.)

## Phase 1: Discovery

### Step 1.1 — Check `remotion-best-practices` availability

Attempt to invoke the `remotion-best-practices` skill via the Skill tool. If unavailable, present:

> "The `remotion-best-practices` skill isn't installed. Options: > a) proceed with baseline Remotion knowledge (quality may be reduced) > b) wait while you install it > c) cancel"

If the user picks (a), emit a warning in the final summary noting reduced quality.

### Step 1.2 — Analyze input

| Input type | What to read | |---|---| | Marketing brief | positioning, key messages, audience | | Blog post | headline, narrative, examples | | Changelog | highest-impact entry | | PR | `gh pr view <n> --json title,body,files,labels`, diff (`gh pr diff`), commit messages, linked issues | | Git refs | `git diff <range>` + `git log <range> --oneline` | | Codebase path | read the specified files/directories | | Freeform | parse the user's description |

For PRs with 20+ files, filter to user-facing changes only — skip `tests/`, `ci/`, `.github/`, lockfile changes, dep bumps.

**Error handling:** - `gh` not available → tell the user, ask for an alternative (diff file, freeform description) - Invalid PR/ref → ask user to verify - File not found → ask for the correct path

### Step 1.2a — PR deep analysis (when input is a PR)

When the input is a PR, the brief table in Step 1.2 is not enough. PR bodies are routinely vague, outdated, or focused on implementation rather than user value, and a video built off the body alone tends to overclaim or miss the headline angle entirely. Before continuing to Step 1.3, run this structured analysis and produce a written **PR analysis block** that becomes the source of truth for Steps 1.4 (scope confirmation), Q2.1 (duration ladder), and Phase 3 (narrative planning).

**Mandatory steps — do all of them:**

1. **Pull metadata and identify the base branch.** ``` gh pr view <n> --json number,title,body,baseRefName,headRefName,files,labels,commits,additions,deletions ``` Record `baseRefName` (usually `main` / `master` / `develop`) — that is the diff reference. `gh pr diff <n>` automatically compares the PR head against this base.

2. **Pull the full diff against the base.** ``` gh pr diff <n> ``` For very large PRs (>500 lines or >20 files), also list changed files via `gh pr view <n> --json files`.

3. **Filter to user-facing surfaces.** Ignore (do not let these shape the headline angle): `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `__mocks__/`, `ci/`, `.github/`, lockfiles, dep bumps without behavior change, generated/build artifacts (`dist/`, `build/`, `.next/`), and formatting-only diffs. What remains is the user-facing surface of the PR.

4. **Enumerate the public-API delta.** From the filtered diff, list every change a user could observe or write code against: - New, renamed, or removed `export`s (functions, types, components, hooks, classes, constants) - New CLI commands, flags, or environment variables - New routes, endpoints, or event names - New config keys or schema fields - Changed default values for existing public surfaces - Changed error messages, log shapes, or response shapes the user could rely on

Grep the diff for added lines beginning with `export `, new top-level `function`/`class`/`const` in `src/` / `lib/` / `packages/*/src/`, new files in those trees, and changes to public type signatures. **If you cannot point at a line in the diff for a claimed API, the claim is wrong — drop it.**

5. **Enumerate the behavior delta.** Beyond API surfaces, list user-visible behavior changes: UI elements added/changed (with file references), CLI / network output that looks different, side effects firing under new conditions, removed limitations, performance characteristics that changed.

6. **Write the before / after value statement.** Exactly two sentences, both grounded in concrete diff evidence: - **Before:** *"Before this PR, a user who wanted to ___ had to ___."* - **After:** *"After this PR, the same user can ___."*

The "had to" half must be a real prior workflow you can describe — copy-pasting an adapter from the docs, installing a second package, writing boilerplate, hitting an error, switching to a different tool. If the honest "Before" sentence is *"they could already do this"*, the PR has no user-visible value delta — see step 8.

7. **Cross-check the PR body against the diff.** Walk the body's claims and the diff side-by-side: - **Body claims a feature → does the diff confirm?** If the body says "added X" and the diff has no public surface for X (only tests, only docs, only internal helpers), flag it: *"PR body claims X but the diff doesn't expose X to users — should I shift the angle to <what the diff actually shows>?"* - **Diff shows multiple distinct features → body emphasizes one?** Flag the others as candidate angles: *"The body emphasizes A, but the diff also adds B and C. Which is the headline angle?"* - **Body is empty / boilerplate / `[BLANK]`?** Infer from the diff; make the inferred angle explicit and confirm with the user at Step 1.4. - **List "surprises"** — anything in the diff *not* mentioned in the body that affects user-visible behavior. Surprises are often the real story.

8. **Bail-out check: is this PR actually user-visible?** If after steps 4–6 you cannot name a single new thing the user can do or observe, the PR is not video-worthy as a feature launch. **Stop and ask the user:** > "This PR looks like an internal refactor / test-only / dep-bump PR — I can't find a user-visible value delta. Options: > a) shift to a performance / DX / cleanup angle if numbers support it > b) pick a different PR or input > c) cancel"

Do not invent a feature angle to fill the gap. A confabulated angle wastes a full iteration round and destroys user trust on the very first draft.

9. **Produce the PR analysis block.** Write the result as a short structured block before continuing to Step 1.3. This block — not the PR body — is the source of truth for everything downstream:

``` PR analysis — #1234 "Add fromZodSchema support" Base: main · Head: feature/zod-schema · Author: <login> User-facing files: 3 (packages/core/src/index.ts, packages/core/src/zod.ts, packages/core/src/types.ts) Filtered out: 5 test files, 2 doc files, lockfile

Public-API delta: + export function fromZodSchema(schema: ZodSchema): StandardSchema + export type ZodCompatibleSchema ~ default error code for ZodError changed: 'invalid_type' → 'STANDARD/type'

Behavior delta: - Users importing zod schemas no longer need a manual adapter. - Error messages from zod paths now use the StandardError shape.

Before / after: Before: copy a 15-line adapter from the docs into every project that mixes zod with this library. After: one import + one call.

Surprises (in diff but not in PR body): - Default error shape change (above) — could be the headline angle for migration-aware audiences.

Headline angle: "drop the 15-line adapter — one import, one call" Scope band for Q2.1: one idea (15–25s) ```

The "Headline angle" line feeds Phase 3.0's motif derivation and Phase 3.3's hook copy. The "Scope band" line feeds Q2.1's scope-derived duration proposal.

10. **Forbidden shortcuts** (each is a fast path to a wrong video): - Writing the analysis block from the PR title alone — **fail**; you must read the diff. - Skipping the cross-check because the body "looks complete" — bodies often look complete and are wrong. - Treating the PR body as truth when it conflicts with the diff — **the diff wins**. - Filling in a plausible "Before" sentence when the diff doesn't support one — run the bail-out check instead. - Collapsing two genuinely distinct user-visible features into one "feature X" bullet to make the scope band look smaller — record both and pick a headline angle at Step 1.4.

**For git-ref-range and codebase-path inputs**, apply the same structure with the diff coming from `git diff <range>` / direct file reads in place of `gh pr diff`. Steps 4–9 (public-API delta →