hyperframes/skills/pr-to-video/phases/scriptwriting/guide.md

Story-Design (PR → narrative)

Core Principles

• Scene sequence comes from narrative design, not from the diff's file order or the commit list order.
• A PR's files may be touched in any order; a video runs hook → the change → why it matters → ship, or bug → root cause → fix → result, or what's new (×N) → wrap, depending on the archetype.
• Reorder, merge, omit, compress. Surface the one change that matters; drop the incidental churn (lockfile bumps, formatting, test scaffolding) unless it is the story.
• The PR is the source of information, not a story template. The single most common failure is narrating the diff file-by-file or reading the PR description aloud — do not do that. Explain the change.

The planning standard: write the emotional beat alongside the structural type, name the specific rhetorical / clarity technique (not merely "explain the change"), and specify a transition for every seam.

Use site_dna to Set the Register (optional, read once at the start)

design-system/inference.json site_dna is the deterministic Phase 1 register summary. If present, read only the site_dna section once and tune narration to the same channel as the final visuals (do not read design.html / chunks/ — parallel design-system outputs; reading them breaks Phase 1b∥2 parallelism). If inference.json is missing, proceed without it.

The shipped style is claude (warm editorial, considered, a serif that thinks, scarce coral, a navy code window). Absent any other signal, default narration to a plain, technical, unhurried developer voice — accurate, specific, no hype, no marketing gloss. You are talking to engineers about a real change; respect their time and their intelligence.

site_dna field	How to use it
voice_tone (warm / neutral / formal)	warm allows a wry aside; neutral is sharp-but-plain; formal stays restrained. Default to neutral-technical.
voice_heading_style / voice_heading_length	tight → short claims / single-line statements; loose → a setup line then the point.

site_dna is a soft input: it tunes voice. The archetype and scene segmentation are driven by the PR + the decision below.

PR Archetypes

Before segmenting scenes, choose one archetype (or explicitly name a compound). Each is a complete, coherent path through understanding a change — do not splice phases from different archetypes.

**Changelog** — "here's what shipped." A hook naming the headline, then **2-4 roughly co-equal change items**, then a wrap / ship line. Best for: release PRs, multi-change PRs, "what's new in vN." Items are usually parallel → default to `cut` / `slide` between them; use `morph` only when a real throughline survives item→item. Rule-of-three is the strongest item count when the changes compress. Type spine: `hook` → run of `feature_showcase` (one per change) → `cta`/`branding`. **Feature-Reveal** — "we built X; here's what it does." Hook (the new capability) → name the feature (`product_intro`) → show it working: the new code typing on, or the new behavior (`feature_showcase`) → impact / why (`benefit_highlight`) → close. Best for: a PR that adds **one notable feature**. The new code is the centerpiece; the feature is a single protagonist. The code-window often persists across 2-3 scenes as it fills in → a `continue` run with `morph` on the code-window. **Fix-Explainer** — "this was broken; here's the fix." Setup the symptom / bug / pain (`pain_point`) → the root cause (`feature_showcase` or `product_intro`) → the fix, as a before→after diff (`feature_showcase`) → the result, now it works (`benefit_highlight`). Best for: bugfix PRs. The diff **is the turn**; the before→after contrast is the strongest beat. Emotional arc has real shape (tension → turn → relief). Pairs naturally with `dissolve` into the cause and a hard `cut` / before-after `morph` on the fix. **Refactor-Walkthrough** — "same behavior, better shape." Hook (the smell / the why) → the old shape → the new shape → the payoff (cleaner / faster / safer, with numbers). Best for: refactors, perf work, cleanups, migrations. Heavy on before→after **structural** comparison (file-tree, call-graph, the diff) and **numbers** (lines removed, perf delta, files touched) to land the payoff. The old→new structure is a genuine shared element → a `continue` run with `morph` works well.

Choosing the archetype

Read the PR once, then ask:

• Is it one notable new capability? → feature-reveal.
• Is it a bug fix? → fix-explainer.
• Is it a behavior-preserving cleanup / perf / migration? → refactor-walkthrough.
• Is it many co-equal changes / a release? → changelog.

Tie-breakers: a feature PR that also fixes a bug → feature-reveal with the fix as one body beat. A fix that required a small refactor → fix-explainer (the fix is the headline). A big PR that's really "one feature + three supporting changes" → "feature-reveal with changelog".

Compound archetypes

Write narrativeArchetype as "<outer> with <inner>", e.g. "feature-reveal with changelog" or "fix-explainer with refactor-walkthrough". Outer = the macro arc the viewer rides; inner = the tactical rhythm inside the body. The downstream visual phase reads it for pacing.

The field name is narrativeArchetype (schema-fixed). For pr-to-video it names the chosen PR archetype. The validator does not constrain its value — any string passes — but pick from the four (or a compound) so the visual phase reads a known shape.

Narrative Architecture

Every scene has five narrative fields (type, narrativeRole, keyMessage, persuasion, emotionalBeat), plus a separate transition spec:

• Type — one of the enum values hook / pain_point / product_intro / feature_showcase / benefit_highlight / social_proof / branding / cta. The enum is schema-fixed (validate-narrator.mjs enforces it), so pr-to-video repurposes these labels for code changes. Use the mapping table below.
• Narrative Role — what this scene does in the explanation (its job, e.g. "Shows the request now retries on 5xx with backoff", not "Shows code").
• Key Message — the one thing the viewer should walk away understanding (one sentence).
• Persuasion — a named rhetorical / clarity technique (catalog below). "Explain the change" is a failure mode; the standard is "Before/after contrast: the throw becomes a retry loop" / "Worked example: one failing request, now recovered."
• Emotional Beat — target feeling (vocabulary below). One word or a short compound phrase. Avoid generic "positive" / "interested".
• Transition — { continuity, intent, description, sharedMotif? }, how this scene arrives from the previous scene. Every scene must have one, including scene 1 (continuity: "break" + intent: "cut").

Type-enum repurposing (schema-fixed enum → PR roles)

The enum values cannot change (validate-narrator.mjs enforces them; at least one scene must be feature_showcase or product_intro). Map your PR roles onto them as follows:

PR role you want	Use enum type	Why this value
Hook / what shipped	hook	The high-leverage opening 3–5s.
Problem / bug / smell / why-care	pain_point	The friction the PR resolves ("every deploy, the same flaky timeout").
Name the change / the feature / the PR itself	product_intro	The "introduce the protagonist" beat — here the protagonist is the change.
The diff / a shipped item / the mechanism	feature_showcase	A unit of the change's body — one before→after, one new function, one list item.
Impact / payoff / what it unlocks	benefit_highlight	The consequence of the change — what now works, what's now possible.
Evidence / metric / +N −M stats / benchmark / test	social_proof	Concrete grounding: a real number, a passing test, a perf delta.
Thesis / principle / takeaway	branding	The landing line — the rule, the one thing to remember.
Try it / upgrade / ship line	cta	The closing ask — pull it, upgrade, read the PR.

The body of a PR video is usually a run of feature_showcase (the changes/diffs) optionally interleaved with benefit_highlight (impact) and social_proof (stats/tests). At least one feature_showcase or product_intro must exist (every PR has a change and a named thing, so this is automatic).

Hook Strategy Taxonomy

Choose one. The hook is the highest-leverage 3–5 seconds:

Strategy	When to use it	Example
Shocking statistic	A change quantifies the stakes	"This PR deletes 1,200 lines." / "40% faster cold starts."
Counterintuitive claim	The change contradicts intuition	"We made the client slower — and that fixed it."
Pain validation	The audience already feels the bug	"Every deploy, the same flaky timeout."
Concept announcement	The change has a name worth landing	"Meet retry-with-backoff."
Before/after teaser	The diff is the whole story	"One line threw. Now it recovers."
Stakes / consequence	The "why care now" is a real cost	"This crash hit every user on a flaky network."
Direct address	The audience is clearly defined	"If you've ever waited on a 5-minute CI run…"

Rhetorical / Clarity Technique Catalog

Each scene's persuasion is a named technique, not a vague intent. Choose from this catalog (combine when several are active):

Family	Techniques
Make-concrete	Worked example (one real request / one real input) • Analogy (backoff as "knock, wait longer, knock again") • Concretization (abstract change → one tangible code line)
Reveal-in-order	Progressive disclosure (the diff one line at a time) • Build-up (the simple call, then the edge case) • Signposting ("before… after…")
Contrast	Before/after diff • Old shape vs new shape • The bug vs the fix • Two approaches compared
Structure	Rule of three (three changes) • Numbered enumeration • Question→answer • Frame-then-fill (state the shape, then the code)
Evidence	+N/−M stat • Passing test / green check • Benchmark / perf delta • Causal chain (request → 5xx → retry → success)
Memory & landing	Callback (return to the hook's bug) • Distillation (the change in one line) • Generalization (this fix → the principle)

Do not write generic "explain the change" / "show the code." Name the mechanism.

Emotional Beat Vocabulary

emotionalBeat is one word or a short compound phrase (e.g. "Recognition and relief", "Curiosity and clarity"). Avoid generic "positive" / "happy". A PR video rides a comprehension arc:

Negative valley — open the gap (hook / pain_point): curiosity • frustration • recognition • concern • skepticism • "ugh, that bug"

Pivot — orient (product_intro / naming the change): clarity • orientation • anticipation • focus

Build — build understanding (feature_showcase / benefit_highlight / social_proof): comprehension • "aha" • confidence • satisfaction • momentum • conviction • relief (for a fix)

Resolution — land (branding / cta): satisfaction • resolve • confidence • "ship it" • inevitability

Compound beats are often strongest, e.g. "Recognition and relief" (a fix), "Curiosity and confidence" (a feature).

Transition Taxonomy

Every scene's transition describes how it arrives from the previous scene, using two machine fields + prose + (for morph) a shared element name:

continuity — "break" | "continue" (drives worker grouping)

The only machine consequence of continuity is grouping: prep.mjs puts adjacent continue scenes into the same scene worker (cap=3 — a continue run is up to 3 scenes). The one worker that owns a run authors the visual continuity across all its scenes itself, so the seams read as one continuous shot.

• continue = "same worker as the previous scene." Use it for a run of 2-3 adjacent scenes that flow as one continuous shot — a code-window that fills in line by line, a before→after that morphs in place, a counter that advances, a file-tree that grows. The worker authors the flow (and any shared-element morph) inside one continuous stage.
• break = a new worker + an inter-scene Tier-B transition (cut / slide / dissolve / zoom) injected by the harness onto the clip wrappers after assembly.
• Scene 1 is always break (there is no previous scene).

A continue run is at most 3 scenes (cap=3). Many short runs are welcome: run(1,2,3) → break → run(4,5) → break → 6. Use continue only where the scenes genuinely share a continuous stage; a parallel changelog may legitimately use break throughout.

intent — 5 narrative seam intentions (not visual implementation)

Choose one of these 5. This is "narrative-level" vocabulary — what kind of connection the seam is, not blur/direction/duration (visual-design translates those):

Intent	Narrative meaning	Pairs with (soft hint)
morph	One shared element transforms across scenes (the code-window gains lines; the old function becomes the new one; the failing test turns green)	continue
cut	Clean switch; scenes not continuous (new change item, topic shift, high-energy beat)	break
slide	Directional push (next change, next step)	break
dissolve	Soft dissolve / focus shift (into the cause, a quieter beat, time passing)	break
zoom	Camera pushes / pulls through to the next focal point (zoom into a code line, pull back to the file tree)	break

continuity is decoupled from intent (a soft hint). morph naturally pairs with continue; the rest pair with break. Nothing enforces this; choose continuity by whether the scenes share a continuous stage.

sharedMotif — optional hint (names the carried element)

Name the element that carries through the seam, ≤8 words. PR examples: "the request flow" / "the failing test" / "the code window" / "the line count" / "the old vs new function". Only name what it is; do not describe geometry — the downstream worker uses this as the persistent subject inside the continue run. Omit when intent is not morph.

Three tests before choosing morph (don't invent a shared element just to have one):

• Load-bearing in both scenes: it is the visual protagonist in both outgoing and incoming scenes (the code-window, the diff, the data series), not a decoration.
• Naturally co-present: an element that would appear in both scenes anyway.
• The transformation advances the explanation: the morph carries the conceptual jump (the same code gains the retry block; the same test flips red→green), rather than being a flashy pause.

description — 10–30 word visual direction (keep)

Concrete direction for downstream: which file/hunk to show, what morphs/slides, where the eye lands. For a code beat, name the snippet ("the request() retry block, ~6 lines"). For morph, be clear about the handoff (what shape is handed to the next scene).

The PR Body Is a Sequence, Not a Single Scene

A PR video's core is almost always 2–5 body scenes, each advancing one change / one before→after / one item, building understanding cumulatively. The body runs feature_showcase / benefit_highlight / product_intro (interleaved per archetype; the only floor is the schema's ≥1 feature_showcase or product_intro):

• changelog: feature_showcase per change item; usually parallel → default cut / slide.
• feature-reveal: product_intro (name it) then feature_showcase (the code working), often a continue run morphing the code-window, then benefit_highlight.
• fix-explainer: pain_point (symptom) → feature_showcase (cause + fix diff, often a continue morph red→green) → benefit_highlight (result).
• refactor-walkthrough: before→after structure across a continue run, then a social_proof numbers beat.

Group adjacent scenes that share a continuous stage into a continue run (≤3 scenes, one worker); between runs use a break + Tier-B transition. Shape: run(s1,s2,s3) → break → run(s4,s5) → break → ….

Faceless Visuals — assetCandidates is [] by Default

• assetCandidates is [] for every scene by default. It tells downstream "this scene is invented from the brief + diff."
• Exception 1 — a user-provided image: the user explicitly placed a real image in public/ (e.g. an architecture diagram). Then add { "path": "public/<basename>", "description": "<≤25 words>" }. Do not invent paths; do not reference capture/.
• Exception 2 — the credits / shipped-by close (contributor avatars): see below.
• Visual intent (which hunk, before/after, file-tree) belongs in narrativeRole + the transition description; the visual phase reads those.

Optional close: a credits / shipped-by scene (the one relaxation of faceless)

A PR is shipped by people. capture/extracted/people.json lists the real contributors — author (the PR opener), committers (the people who actually wrote/co-authored the commits, with a commitCount), reviewers (each with a reviewState), commenters — bot-filtered and deduped, and the orchestrator has already downloaded each one's GitHub avatar to public/avatars/<login>.png (the avatarFetched: true entries — confirm with ls public/avatars/). The top-level reviewDecision (e.g. APPROVED) is honest grounding.

The PR author is only who opened the PR — not necessarily who wrote the code. A teammate frequently authors most commits and force-pushes the branch. Lead the credits with the committers by commitCount, not the opener, or you'll miss the main contributor.

You may add a single closing scene that names the humans behind the change — a branding ("shipped by …") or social_proof ("approved by 3 reviewers") beat. On that scene only:

• assetCandidates = an array of { "path": "public/avatars/<login>.png", "description": "<login>, <role>" }, 2-6 entries, commit authors (by commitCount) first then reviewers, only avatarFetched: true logins.
• The body stays faceless — avatars appear only on this close, never decorating a code/diff scene.
• The visual register is an avatar row / contributor wall with names + roles + an "approved" check (the visual phase already handles non-empty assetCandidates — it features them like real screenshots).

This is optional and tasteful, not mandatory: a one-line hotfix doesn't need a credits roll; a feature or release the team rallied around earns one. When people.json has only the author (a solo PR with no reviews), a credits scene is usually overkill — skip it. The hook/body/payoff arc remains the spine; credits are a grace note at the end.

Per-Scene Length Budget — ≤ 9 s, Word Count Is the Real Measurement

The single largest quality bug in PR videos is scripts that talk too long. The narrator agent tends to write 30-50 words per scene "because the change has nuance," then estimate "7s". The actual TTS at the Phase 3 default voice (ElevenLabs Rachel for technical narration) is ~2.2 words/second (~130 wpm) — so a 45-word script is a 20-second scene, not a 7-second one. The visual phase then has to fill 13 seconds of unplanned tail with sine-wave-loop idle drift, and the viewer reads the whole film as "shimmering."

Budget the script by word count, not by gut-feel seconds. The validator (scripts/validate-narrator.mjs) enforces these as machine checks; failing the hard cap is fatal.

Bound	Words (at 2.2 wps)	Duration	When
Soft target — default	≤ 19	≤ 9 s	Every scene aims for this; visual phase plans tight, idle phase stays short, the cut feels alive.
Exception budget — ≤ 2 scenes	≤ 26	≤ 12 s	The main feature_showcase (the one change you really need to explain) or a complex causal-chain product_intro. Earn the extra seconds; don't spend them on hook / branding / credits.
Hard cap — fatal	> 26	> 12 s	The validator rejects. Trim or split the scene.
Whole-film target	≤ ~400	up to ~3 min	Sweet spot is still ~30-90 s (≤ ~155 words); ~3 min is the ceiling. The body carries the load, the close is 5-8 s.

How to estimate while writing:

estimatedDuration ≈ word_count / 2.2     // round up to the nearest whole second

29-word script → "13s" (over budget, trim). 17-word script → "8s". 12-word script → "6s". The agent's old habit of writing "6s" for a 29-word script is a 2.3× miscalculation that downstream cannot fix.

Trim pass — concrete techniques (apply when a scene comes out 25+ words):

1. Cut the lead-in clause. "Until now, the agent shipped …" → "The agent shipped …". Lead-in framing is implied by the hook; the words don't earn their seconds.
2. Move evidence off-script. Numbers (+2035 lines, 23 files, commit counts) belong as on-screen counters, not narration. The visual phase animates them; the script gains 3-5 seconds.
3. Split into two scenes only as the last resort — split only when the two halves carry distinct emotional beats (cause then effect, problem then fix).

Where exceptions are earned:

• The single most complex feature_showcase — e.g. a 4-step pipeline with a best-effort contract. Allow up to 12s / 26 words.
• A causal-chain product_intro — e.g. "URL → role check → bg-remove → sha256 → durable URL" — the words have to land sequentially with the on-screen edges drawing.
• Never the hook, the branding/credits close, or a single-fact benefit_highlight. These should be the shortest scenes in the film (5-8 s each).

Anti-pattern: "but the change is complex." A complex change does not require a long script; it requires a careful one. If you cannot say the headline of a change in 19 words, the headline isn't sharp yet — write it again. Distillation (line 292) is the strongest persuasion technique in this catalog precisely because it forces this discipline.

Validation Checklist

• Does every scene have complete Narrative Intent (all 5 fields nested under narrativeIntent)?
• Does every scene have transition — continuity (break/continue), intent (one of the 5), description (10–30 words)? Is scene 1 continuity: break? Is every continue run at most 3 scenes?
• Is assetCandidates present on every scene as an array ([] except a user-supplied public/<basename>)?
• Does the emotional arc have meaningful variation matching the archetype (fix = frustration → relief; feature = curiosity → confidence)?
• Is the sequence driven by narrative, not the diff's file order or the commit list?
• Is there a coherent body that builds cumulatively (a run of feature_showcase / benefit_highlight / product_intro), not a single isolated body scene?
• Are Persuasion fields named techniques from the catalog, not "explain the change"?
• Are Emotional beats specific (word or short compound phrase)?
• Does the hook use a named strategy from the taxonomy?
• Is there only one outer archetype (no splicing top-level frameworks)? Named inner-rhythm compounds are allowed.
• Is the type-enum used per the repurposing table (≥1 feature_showcase/product_intro)?
• Did you feature 2-4 real diff hunks (named in transition descriptions), each a small legible snippet — not a whole file?
• Did each scene's script fit the budget — ≤ 19 words / ≤ 9 s as the default, with no more than 2 scenes claiming the ≤ 26 words / ≤ 12 s exception? Did you compute estimatedDuration as ceil(word_count / 2.2) for each, not guess? (See "Per-Scene Length Budget" above; scripts/validate-narrator.mjs enforces the hard cap and warns on the soft target.)

narrator_scripts.json: Canonical Schema

Downstream agents expect these exact field names. Wrong names (e.g. scene_id instead of sceneNumber, narration instead of script, or flattened intent fields) are fatal in validate-narrator.mjs.

{
  "project": "Project name",
  "narrativeArchetype": "PR archetype (changelog | feature-reveal | fix-explainer | refactor-walkthrough), or compound \"<outer> with <inner>\"",
  "orientation": "Canvas aspect, echoed verbatim from the dispatch Orientation line: landscape (16:9, default) | portrait (9:16) | square (1:1). Dictated by the user's aspect, not chosen. prep maps it to group_spec.width/height. Omit → landscape.",
  "emotionalArc": "Comprehension journey (e.g. 'Frustration at a flaky timeout shifting to relief as the retry loop recovers the request.')",
  "scenes": [
    {
      "sceneNumber": 1,
      "sceneName": "Scene name",
      "transition": {
        "continuity": "break|continue",
        "intent": "morph|cut|slide|dissolve|zoom",
        "sharedMotif": "Only when intent=morph: the element carried across scenes (<=8 words, e.g. 'the code window'); omit this key otherwise",
        "description": "10-30 word concrete visual direction: which hunk/file to show, what morphs/slides, where the eye lands"
      },
      "narrativeIntent": {
        "type": "hook|pain_point|product_intro|feature_showcase|benefit_highlight|social_proof|branding|cta",
        "narrativeRole": "The scene's job in the explanation (not what appears on screen)",
        "keyMessage": "What the viewer should understand after this scene (one sentence)",
        "persuasion": "Named rhetorical/clarity technique from the catalog (combine if multiple are active)",
        "emotionalBeat": "Word or short compound phrase from the vocabulary"
      },
      "assetCandidates": [],
      "script": "Plain-text narration ≤ 19 words for the soft target (≤ 9 s) — only the main feature_showcase / a causal-chain product_intro may push to ≤ 26 words. May include <em>/<brand>/<emph>/<cta> tags as authoring annotations (TTS strips them). Can be \"\" when visuals carry the information (e.g. a diff typing on).",
      "estimatedDuration": "8s   // = ceil(word_count / 2.2). Realistic ElevenLabs Rachel TTS rate is 2.2 wps; do not guess by feel — the validator catches drift."
    }
  ]
}

Field rules:

• Use sceneNumber (not scene_id), sceneName (not scene_name), script (not narration), and nest intent fields inside narrativeIntent (do not flatten them onto the scene object).
• Every scene must have a transition field (continuity + intent + description; add sharedMotif for morph), including scene 1 (continuity: "break" + intent: "cut"). Scene 1's transition does not generate any transition downstream (it's ignored) — intent: "cut" is just a placeholder.
• continuity is decoupled from intent (a soft hint). continue = same worker (a run of up to 3 scenes); break = new worker. validate-narrator.mjs checks only enum membership + scene 1 = break.
• assetCandidates is a required field and must be an array. For pr-to-video it is [] on essentially every scene; only a user-provided public/<basename> image yields a {path, description} entry (path must start with public/).
• At least one scene must be type: feature_showcase or product_intro.
• Empty script is allowed when the visual carries the information (a diff typing on, a before→after morph, a counter running). When you set script: "", make narrativeRole especially strong.

Script Voice Quality Bar

Strong PR-video scripts are clear, voiced, and technical-but-human. The failure mode is reading the PR description aloud, or noun-phrase bullets.

Strong:

• Before/after: "Before, a 500 just threw. Now the client waits, backs off, and tries again." — names the exact change.
• Distillation: "Eighty-four lines added, one real idea: retry, don't give up." — compresses the diff to its point.

Weak (avoid):

• Diff-paraphrase in order: "This PR modifies request.js, adds backoff.js, and updates package-lock.json." — that's reading, not explaining.