# Retention-led render planning

Use this when a shorts automation project has finalized scripts but the renderer still risks producing generic AI slideshow output.

## Durable lesson

Do not jump directly from script text to rendered video. Insert a deterministic shot-planning layer first. The shot plan should preserve the content strategy and give the renderer specific visual direction.

## Recommended sequence

1. Finalize the voiceover script.
   - Keep hook first.
   - Estimate duration from word count.
   - Preserve platform intent, e.g. short growth clip vs. 60s+ TikTok Rewards candidate.

2. Generate a structured five-scene shot plan.
   - `first_frame_hook`
   - `pattern_interrupt`
   - `core_explanation`
   - `screen_or_card_visual`
   - `cta`

3. Include renderer-facing fields for each scene.
   - timing window
   - asset type
   - on-screen text
   - visual direction
   - retention goal

4. Use asset types that prevent generic slideshow output.
   - `kinetic_text` for hook/CTA
   - `screen_recording` for AI/tutorial content
   - `card_animation` for mental models and frameworks
   - `stock_broll` only where it supports a relatable action or state change
   - avoid default static AI-image backgrounds unless the visual concept explicitly needs them

5. Render only after the shot plan exists.
   - Prefer generating a structured render manifest from the shot plan before invoking the renderer.
   - Start with one test video before batch rendering.
   - Send preview for human approval before publishing.

## Testing pattern

For code-based pipelines, use TDD around the shot planner:

- Write tests that assert the five scene purposes, asset-type choices, and first-frame hook handling.
- Verify RED by importing a missing/new planner module or asserting missing behavior.
- Implement the minimal deterministic planner.
- Verify generated Markdown or JSON includes shot plan, caption beats, and asset-type fields.
- Run the full test suite before commit/push.

## Example output shape

```yaml
id: ai-004
title: Stop asking AI to think for you
estimated_seconds: 43
scenes:
  - purpose: first_frame_hook
    start: 0
    end: 3
    asset_type: kinetic_text
    on_screen_text: Stop asking AI to think for you. Ask it to argue with you
    visual_direction: Large kinetic hook text over a messy prompt window; immediate zoom-in on the contradiction.
    retention_goal: Stop the scroll with self-relevance and tension in the first two seconds.
  - purpose: pattern_interrupt
    asset_type: screen_recording
  - purpose: core_explanation
    asset_type: card_animation
  - purpose: screen_or_card_visual
    asset_type: screen_recording
  - purpose: cta
    asset_type: kinetic_text
```

## Pitfall

A visually clean render can still be strategically bad if it looks like generic AI slideshow wallpaper. The renderer should follow a retention shot plan, not merely decorate a script.