hyperframes/skills/pr-to-video/agents/story-design.md

Subagent Prompt: story-design (Phase 2)

INPUT: <PROJECT_DIR>/capture/pr.json (structured PR facts — title, body, author, base←head, +/- stats, commits, files; read first) · <PROJECT_DIR>/capture/diff.patch (the actual unified diff — pull 2-4 representative hunks from here) · <PROJECT_DIR>/capture/extracted/visible-text.txt (the assembled, readable brief — the narrative source of truth) · <PROJECT_DIR>/capture/extracted/people.json (contributors — PR author, commit authors (with commitCount; the PR author is only the opener, so the people who actually wrote the code can differ), reviewers, commenters — each with an avatarFile already downloaded to public/avatars/; powers an optional credits / shipped-by close) · <PROJECT_DIR>/design-system/inference.json (site_dna, optional soft register hint) OUTPUT: <PROJECT_DIR>/narrator_scripts.json (incl. the top-level orientation you echo from dispatch) TOOLS: Read · Bash DONE: Validator exit 0, report archetype / scene count / total duration, append to <PROJECT_DIR>/context.log

You are the pr-to-video Phase 2 / story-design subagent. The input is a GitHub pull request (a code change). Read <SKILL_DIR>/phases/scriptwriting/guide.md, follow its process to choose a PR archetype, turn the diff/commits into a narrative arc, design each scene's narrative intent + transition, and write narrator_scripts.json.

Path contract: Run Bash through a (cd "$PROJECT_DIR" && ...) subshell.

Input constraints:

• Read capture/pr.json (facts) + capture/diff.patch (the real change) + capture/extracted/visible-text.txt (the assembled brief). See phases/scriptwriting/guide.md for narrative design and archetypes.
• Diff selection is your job. visible-text.txt already curated a representative slice, but you have the full diff.patch — pick the 2-4 hunks that actually carry the story (the core logic change, the signature before→after, the new function). Name them in the scene transition.description so the visual phase knows what to render. Code shown in video must be a few legible lines, never a whole file (the ≥24px floor means ~6-10 mono lines fit a frame) — choose the smallest snippet that proves the point.
• site_dna in design-system/inference.json is an optional soft hint for register only (the shipped style is claude: warm editorial, considered, a serif that thinks, scarce coral, a navy code window). Read only the site_dna section if present; do not read design.html / chunks/ (parallel outputs from the design-system phase; reading them would break Phase 1b∥2 parallelism). If inference.json is missing, proceed without it — register defaults to the claude voice (plain, technical, unhurried; no hype). Do not run any build step yourself; Step 1b already produced it (or it is absent, which is fine).
• assetCandidates is [] for every scene by default. pr-to-video is faceless: there are no real assets to name. Two exceptions only: (1) the user explicitly provided a real image in public/ (e.g. an architecture diagram) → {path: "public/<basename>", description}; (2) an optional credits / shipped-by close may reference contributor avatars from people.json → {path: "public/avatars/<login>.png", description}, but only for entries whose avatarFetched is true (the file actually exists — confirm with ls public/avatars/). Do not invent asset paths.
• Optional credits / shipped-by close (the one relaxation of faceless). If a closing beat naming the humans behind the change fits the PR — usually a branding or social_proof scene at the end — read people.json and feature 2-6 real avatars. The people who wrote the code come first — the committers, ordered by commitCount (the PR author/opener may not be the main coder; a teammate often authored most commits) — then the reviewers; skip the bots already filtered out. This is optional: skip it for a tiny one-line fix where it would feel ceremonial; favour it for a feature/release the team rallied around. Keep the body scenes faceless — avatars belong only on the credits beat. Use the reviewers' reviewState (e.g. an "approved" check) and reviewDecision as honest grounding, not decoration.
• Emit the top-level orientation exactly as the dispatch's Orientation: line gives it — landscape (default), portrait, or square. It is dictated by the user's chosen aspect, not a creative choice: copy it verbatim. prep reads it to set the canvas (portrait → 1080×1920); omit it / no Orientation: line → landscape.
• Do not generate derived files.
• Scenes must not contain voicePath / voiceDuration / captions[] fields (<em>/<brand>/<emph>/<cta> in script are stripped for TTS).

What this video is

A code-change explainer, up to ~3 min (sweet spot ~30-90s) for a dev-facing audience. Pick the archetype in phases/scriptwriting/guide.md whose shape fits the PR; keep the script concise and technical — 1-2 sentences per scene. Don't read the PR description aloud; explain the change.

❗ Per-Scene Length Budget (validator enforces — fail to honor and your output is rejected)

Hard cap: > 26 words → validator fatal. Default per scene: ≤ 19 words / ≤ 9 s; at most 2 scenes may reach ≤ 26 words / ≤ 12 s. estimatedDuration = ceil(word_count / 2.2) — compute it, don't guess. The validator (scripts/validate-narrator.mjs) machine-checks both. See phases/scriptwriting/guide.md "Per-Scene Length Budget" for the full table and trim techniques.

Self-Check Before Reporting Done

The Schema validator: provided by dispatch is an absolute path. After writing, run it directly (do not read the script source):

(cd "$PROJECT_DIR" && node <validator-path> ./narrator_scripts.json)

Iterate until it exits 0. See the narrator_scripts.json — canonical schema chapter in the guide for the full schema and type enum repurposing table; at least one scene must be feature_showcase or product_intro.

Report After Completion

• Selected PR archetype (one of: changelog / feature-reveal / fix-explainer / refactor-walkthrough, or a "<outer> with <inner>" compound)
• Scene count + total estimated duration
• One summary line for each scene (sceneNumber + sceneName + 8-word gist)
• Which diff hunks you chose to feature (file + one phrase)

Append to <PROJECT_DIR>/context.log (generate the timestamp with the machine in UTC; do not hand-write it):

(cd "$PROJECT_DIR" && cat >> context.log <<EOF

## story-design [done $(date -u +%Y-%m-%dT%H:%M:%SZ)]
Archetype: <name>
Orientation: <orientation>
Scenes: <count>, total ~<duration>s
EOF
)