---
name: breakdown
description: SUPERSEDED by Starsend Global Bible (Stage 1). Legacy script breakdown — extract visual production assets from episodes.
allowed-tools: Read, Write, Bash, Glob
argument-hint: "[project] [ep N-M] [--refresh | --prompts ref|flux2 | --status]"
---

# /breakdown — Script Breakdown System

Extract every visual production asset from episode scripts. Produces structured JSON consumed by the Breakdown Editor and downstream storyboard/frame/video generation pipeline.

**Architectural role:** This system IS the "Asset Database" and "Global Context Manager" described in the Flux 2 pipeline research. Every asset extracted here becomes a conditioning reference for downstream production.

## Usage

```
/breakdown leviathan                       # Full: extract + enrich + validate + report
/breakdown leviathan ep 1-10               # Range only
/breakdown leviathan ep 5                  # Single episode
/breakdown leviathan --refresh             # Re-scan, merge with existing locks
/breakdown leviathan --prompts ref          # Generate reference prompts for all assets
/breakdown leviathan --prompts flux2       # Generate Flux 2 structured prompts
/breakdown leviathan --prompts ref ep 1-10 # Reference prompts for range
/breakdown leviathan --status              # Lock progress report
```

## What It Produces

A single JSON file at `/[project]/visual/breakdown.json` conforming to `/templates/breakdown_schema.json`.

The JSON contains:
- **Characters** — Visual descriptions, wardrobe phases, hair/makeup states, reference image slots
- **Locations** — INT/EXT types, description samples, lighting notes, reference slots
- **Props** — Signature and detected props with confidence levels, owner mapping
- **SFX Elements** — Promptable effects (fire, smoke, sparks) with production method
- **VFX Elements** — Post-composite effects (AR overlays, HUDs) with color values
- **Specialty Shots** — Extended clips needing sandwich workflow or complex motion
- **Audio Flags** — VO, ambient, music cues per episode
- **Shot Estimates** — Per-episode and per-character shot counts
- **Asset Lock Status** — Progress toward production readiness

## Parameters

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `project` | Yes | — | Project folder name |
| `ep N` or `ep N-M` | No | All 60 | Episode range to process |
| `--refresh` | No | — | Re-scan and merge with existing locks |
| `--prompts ref\|flux2` | No | — | Generate reference or Flux 2 prompts |
| `--status` | No | — | Lock progress summary only |

## Two-Pass Architecture

The extraction pipeline uses a Gemini → Opus two-pass architecture:

1. **Python regex extraction** (fast, deterministic) → asset checklist + dialogue counts
2. **Gemini structural synthesis** (all episodes → `global_bible.json` via Starsend ingest pipeline)
3. **Python validation** (compare regex checklist against Gemini output — any missing assets?)
4. **Opus prose enrichment** (per-asset descriptions, reference prompts)
5. **Derive breakdown.json** from `global_bible.json` (pure schema translation, no LLM)

`global_bible.json` is the canonical structural data. `breakdown.json` is derived from it with
Recoil-specific fields (reference slots, prompts, lock status) added.

## Execution

When this skill is invoked, follow the agent protocol in `/agents/breakdown_agent.md`.

### Quick Summary

1. **Run regex extraction** — `python3 /tools/script_breakdown.py /[project]/`
2. **Run Gemini structural synthesis** — Camera-test + breakdown pass via Starsend pipeline
3. **Derive breakdown.json** — `python3 /tools/derive_breakdown.py path/to/global_bible.json /[project]/`
4. **Opus enrichment** — Rewrite skeleton fields with dense prose, generate reference prompts
5. **Validate** — `python3 /tools/validate_breakdown.py /[project]/visual/breakdown.json /[project]/`
6. **Fix errors** — If tier 1 errors, fix and re-validate (max 3 attempts)
7. **Report** — Summary with warnings and next steps

### Mandatory Validation

After extraction, the agent MUST run:

```bash
python3 /tools/validate_breakdown.py \
  /[project]/visual/breakdown.json \
  /[project]/ --report
```

This checks:
- **Tier 1 (Hard Errors):** All episodes processed, all characters present, visual descriptions exist, wardrobe covers all episodes
- **Tier 2 (Warnings):** State change continuity, prop ownership, location consistency, story day gaps
- **Tier 3 (Info):** Prompts populated, reference paths valid, VFX methods assigned

**Exit codes:** 0 = clean, 1 = hard errors (blocks production), 2 = warnings (requires review).

**Do NOT proceed until tier 1 is clean.** Tier 2 warnings require review but don't block.

### Prompt Generation (--prompts flag)

When `--prompts ref` is specified, generate rich photorealistic engine-agnostic reference prompts (60-120 words) for every asset. No engine-specific flags — the batch generation script handles those.

*Character hero shot:*
```
Extremely candid, photorealistic [angle] shot of [subject identity],
[age, ethnicity, skin details: freckles, pores, texture, scars],
[hair: style, condition, color], [build/body type],
[wardrobe: specific clothing with material, wear, damage],
[signature props on body], [expression/mood],
[environment], [lighting: style, direction, color temperature],
ultra-detailed, true-to-life, cinematic realism,
emphasizing skin texture and material detail
```

*Character wardrobe variant (1 prompt per variant, batch script adds angles):*
```
[Wardrobe: specific clothing with material type, wear, damage],
[accessories/gear: tools, devices, items worn],
[physical state: injuries, grime, sweat, blood],
[hair/makeup state matching phase],
[posture/bearing changes], [key visual tells]
```
The variant prompt is a rich wardrobe/state description (60-120 words). `batch_generate_refs.py` generates **5** angle shots per variant (front, profile, three-quarter, full body, back) by prepending angle instruction + character identity.

*Locations:*
```
Photorealistic wide establishing shot of [location],
[architectural details: materials, scale, condition, decay],
[atmosphere: particles, haze, humidity], [lighting: sources, color temperature],
[environmental storytelling details], cinematic composition, deep focus, ultra-detailed
```

*Props:*
```
Photorealistic product shot of [prop], [material: type, condition, wear],
[color and finish details], [mechanical details if applicable],
[lighting], dark background, ultra-detailed, macro detail
```

For characters, the `prompts.reference` field in breakdown.json is a structured object with `hero` (identity prompt) and `variants` (a map of variant name → single wardrobe description string). The batch script generates 5 angle shots per variant. See `/agents/breakdown_agent.md` for the full JSON schema.

**Flux 2:** Structured JSON per `/appendix_e_flux2_protocols.md` (separate format for storyboard production frames).
```json
{
  "scene": "[novelistic prose, 30-80 words]",
  "subjects": [{ "id": "[key]", "reference_index": 2, "description": "[visual]", "action": "[pose]" }],
  "camera": { "angle": "eye", "lens": "50mm f/2.0", "film_stock": "Kodak Vision3 500T" },  // lens per CONSTANTS.md
  "lighting": { "type": "cinematic", "source": "[from lighting notes]" },
  "color_palette": ["#hex1", "#hex2"],
  "mood": "[from character emotional state]"
}
```

### Output Path

```
/[project]/visual/breakdown.json
/[project]/visual/refs/characters/    # Reference images (populated via Breakdown Editor)
/[project]/visual/refs/locations/
/[project]/visual/refs/props/
/[project]/visual/refs/vfx/
```

## Downstream Consumers

| Consumer | What It Reads |
|----------|---------------|
| **Breakdown Editor** (Production Console → Breakdown tab) | Full JSON — visual management |
| **Storyboard Agent** | Character visuals, wardrobe phases, props, VFX list |
| **Frame Generation** (ComfyUI) | Reference images from locked assets, Flux 2 prompts |
| **Continuity Tracking** | Hair/makeup states, wardrobe phases, story day timeline |

## Flux 2 Reference Slot Protocol

| Slot | Purpose | Source |
|------|---------|--------|
| 1-5 | Character identity (front, profile, 3/4, full body, **back**) | Reference batch |
| 6 | Props/wardrobe (signature item) | Reference batch |
| 7-8 | Environment/location (wide + detail) | Location refs |
| 9 | Lighting reference (mood) | Look-dev images |
| 10 | Pose/structure (depth map, layout) | Storyboard |

The breakdown system tracks which slots are populated per asset and reports readiness in the Summary tab.

**Note:** This slot assignment also affects storyboard generation — the storyboard agent reads slot assignments when composing frame prompts.

## Related

- **Schema:** `/templates/breakdown_schema.json`
- **Agent protocol:** `/agents/breakdown_agent.md`
- **Extraction script:** `/tools/script_breakdown.py`
- **Validation script:** `/tools/validate_breakdown.py`
- **Visual editor:** Production Console → Breakdown tab (`/editors/_standalone/breakdown_editor.html`)
- **References editor:** Production Console → References link (`/editors/_standalone/references_editor.html`)
- **Visual QC tool:** `/tools/visual_qc.py`
- **MJ V7 protocols (legacy):** `/appendix_f_midjourney_v7_protocols.md`
- **Flux 2 protocols:** `/appendix_e_flux2_protocols.md`