---
name: script-analysis
description: Decompose raw scripts into structured Act/Scene folders, detect input detail level, and extract metadata.
---

# Script Analysis Skill

## Purpose
Convert raw script text into the project's filesystem structure AND extract structured metadata for downstream agents.

## Input Level Detection

Before processing, detect what level of detail the input provides:

| Level | Detection Clues | What This Skill Does |
|---|---|---|
| **Level 1** (Prose) | Bullet points, no `SHOT N` markers | Scaffold folders + extract characters/locations + flag for full shot planning |
| **Level 2** (Shot list) | `SHOT N` markers, dialogue blocks, minimal camera specs | Scaffold folders + extract shot data + flag for camera enhancement |
| **Level 3** (Camera script) | `SHOT N – [TYPE]`, camera directions, action beats | Scaffold folders + extract all data + validate completeness |
| **Mixed** | Prose sections + `## Shot Division` sections (like `detailed_script.md`) | Process each section at its detected level |

## Core Responsibility: AI-Aware Cinematic Breakdown
Scripts are often written in loose prose or traditional screenplay formats that don't map 1:1 to modern AI video generation workflows. Your job is to read the raw script and break it down into a strict, executable shot list while respecting AI model limitations (specifically, Veo 3.1).

### The Breakdown Philosophy
1.  **Read for Intent**: Understand the narrative goal of the scene.
2.  **Chop by Action/Time**: An AI model cannot generate a 30-second continuous action sequence well. You must segment long actions into 4-8 second logical beats.
3.  **Chop by Camera Reset**: If the prose implies a perspective shift (e.g., "Veeran looks out the window. The army marches below."), those are two distinct shots, not one generation.

## AI Limitation Constraints (Veo 3.1)

When determining shot boundaries, you must strictly adhere to these constraints:

| Constraint | Rule for Breakdown |
|---|---|
| **Max Duration** | Shots **cannot exceed 8 seconds**. If an action takes ~15 seconds to describe, you MUST cut it into at least two shots (e.g., Shot A: Wide establishing action; Shot B: Close-up finishing action). |
| **Dialogue Limits** | AI audio generation degrades with long speech. Limit dialogue to **~12 words max** per shot. Break long monologues into multiple rhythmic cuts. |
| **Action Complexity** | AI struggles with highly complex, multi-stage physics (e.g., "He runs, jumps the fence, tackles the guard, and steals the keys"). Break this down into 3 separate, simple shots: 1 (run/jump), 2 (tackle), 3 (keys). |

## Workflow

### Step 1: Analyze Input & Extract Metadata
Scan the provided script slice:
- Identify Characters (note physical states/costumes required for this specific scene).
- Identify Locations & Times of Day (for `scene_status.json` and registry lookups).

### Step 2: The Shot Segmentation (The Crux)
Take paragraph blocks and slice them:

*Raw Script Paragraph:*
> "Veeran bursts out of the hut, screaming in anger. He grabs the heavy wooden cart and pushes it with all his might until it blocks the gate, panting heavily as the dust settles around him."

*Your AI-Aware Breakdown:*
- **Shot 1 (4s)**: Veeran bursts out of the hut, face twisted in anger. (Action: Fast, High Emotion).
- **Shot 2 (6s)**: Veeran's hands grip the heavy wooden cart; he pushes forward. (Action: Strain, Physical setup).
- **Shot 3 (6s)**: The cart slams into the gate, blocking it. Dust settles around Veeran as he pants. (Action: Resolution).

### Step 3: Scaffold & Document
Once the breakdown is complete in your mental workspace:
1. Update `project/scene_status.json` with the newly defined `shot_ids` and their intended durations (4s, 6s, or 8s).
2. Write the formatted breakdown to `project/scripts/Act_X/Scene_XX_[Name].md` for the `storyboard-generation` skill to consume later.
### Step 4: Extract Metadata
Collect project-level metadata while reading:
- **Characters**: Name, physical description, costume notes.
- **Locations**: Name, INT/EXT, time of day.
- **Dialogue**: Extract and format (with translations if present) for the `video-generation` skill to use later.

## Output
Produce a validated scene markdown file (`project/scripts/Act_{X}/Scene_{XX}_[Name].md`) containing:
1. Scene heading and metadata.
2. The sequentially numbered, AI-constrained Shot List (with durations).
3. Append any new characters/locations to `project/reference_registry.json` placeholders if they don't exist.

## Rules
1. **Never exceed 8 seconds** per shot. AI models will fail or hallucinate.
2. **Never exceed ~12 words of dialogue** per shot.
3. **One Action = One Shot**. Do not stack complex actions temporally in a single prompt.
4. **Preserve Original Text**: When adapting dialogue, never alter the scriptwriter's actual words or language (e.g., Tamil).