# Breakdown System — Backlog & Open Questions

> Issues, improvement ideas, and architectural decisions discovered during first production run (Leviathan eps 1-5, 2026-01-31).

---

## Core Architecture Question

**Should the Python extraction script exist at all?**

| Approach | Pros | Cons |
|----------|------|------|
| **Current: Script + Claude enrichment** | Systematic coverage, mechanical scan ensures nothing missed | False positives create correction work, script doesn't understand context |
| **Claude-only (2 passes)** | No false positives, understands metaphor/context, better wardrobe/hair/makeup | Might miss edge cases, more token-intensive, no deterministic baseline |
| **Fixed script + Claude enrichment** | Best of both if script is good enough | Engineering investment to fix script |

**Current verdict (updated 2026-01-31):** Script was fixed — P1 and P2 issues resolved. False positives reduced dramatically (props 5→3, SFX 11→3, VFX 6→4, specialty shots 3 false→2 true). Script now provides a clean baseline for Claude enrichment. The two-phase workflow (script extraction + Claude enrichment) is the current approach.

**Decision:** Keep fixed script + Claude enrichment. Re-evaluate after processing a full 60-episode run.

---

## Script Issues (if fixing)

### P1 — False Positive Props ✓ FIXED

- [x] **Character names detected as props.** Added `pre_scan_characters()` that scans all episodes for dialogue cues BEFORE prop detection. Also checks individual words of multi-word CAPS phrases against known characters. VAREK SORN no longer appears as prop.
- [x] **VFX elements duplicated as props.** Added VFX/prop dedup pass in aggregation — any prop key matching a VFX key is removed. AR OVERLAY no longer appears as prop.

### P1 — False Positive SFX (Substring Matching) ✓ FIXED

Applied word-boundary matching + exclusion patterns (options 1 + 3):

- [x] "rain" — `\brain\b` no longer matches "drain" or "brain"
- [x] "ice" — `\bice\b` no longer matches "juice", "service", "notice"
- [x] "fire" — exclusion pattern for "line of fire", "open fire", "ceasefire", etc.
- [x] "water" — exclusion pattern for "waterfall", "water down", etc.
- [x] "fog" — word boundary prevents matching "fogs" as verb *(note: `\bfog\b` still matches "fog" as noun — acceptable)*
- [x] "glow" — **removed from SFX_KEYWORDS entirely** (too general, better as lighting/texture in enrichment)

Also removed: `flicker`, `rust`, `corrosion`, `flash` (too general). Removed `display` and `glitch` from VFX keywords.

Result: SFX 11→3, VFX 6→4.

### P2 — Wardrobe Extraction ✓ FIXED

- [x] Wardrobe descriptions now marked `[ENRICHMENT NEEDED] Arc state: {state}` — preserves episode ranges from Transformation Beats table but clearly flags the description as needing Claude enrichment with actual visual wardrobe.

### P2 — Specialty Shot False Positives ✓ FIXED

- [x] Added metadata line filtering (skip `---`, `**` headers, `INT./EXT.` scene headings, dialogue cues)
- [x] Added beat-boundary block breaking (action blocks no longer span multiple story beats)
- [x] Raised threshold to 6+ consecutive action lines with 2+ distinct motion verbs

Result: 3 false positives → 2 true positives (ep 1 vertical fall, ep 4 electrocution).

### P3 — Hair/Makeup Not Attempted

The script doesn't try to extract hair/makeup states. This is probably correct — it's a fundamentally semantic task (understanding progressive deterioration, which injuries persist, when resets happen). Should remain Claude-only.

### P3 — Color Palettes Not Attempted

Same as above. Deriving HEX codes from prose descriptions is Claude territory.

---

## Schema/Structure Issues

### Missing: Background Extras / Crowds

Ep 5 has a crowd scene (6-8 residents with improvised weapons, children in doorways). The "MAN" character is really a crowd representative. Current schema has no way to represent:

- Crowd size and composition
- Crowd wardrobe (generic lower-deck residents)
- Crowd props (improvised weapons — pipes, wrenches, corroded metal)
- Crowd emotional state (angry, scared, debt counters glowing)
- Whether a crowd member needs individual design vs. generic

**Proposal:** Add a `crowds` section to the schema:

```json
"crowds": {
  "lower_deck_mob": {
    "episodes": [5],
    "size": "6-8",
    "composition": "Adults with children behind. Mixed gender. Lower-deck residents.",
    "wardrobe": "Generic lower-deck wear. Patched, worn, desperate. Debt counters on every wrist.",
    "props": ["pipe wrenches", "corroded metal pieces", "improvised weapons"],
    "emotional_state": "Angry, scared. Calculating reward vs risk.",
    "named_members": ["MAN"],
    "production_notes": "Need 6-8 distinct but generic character designs. Children in doorways as separate elements."
  }
}
```

### Location Consistency Across Episodes

This is a real production concern. When a location recurs (e.g., "The Root" appears in ~15 episodes), every frame generated for that location needs visual consistency. Current issues:

1. **Scene heading consistency:** Will the generator always write "INT. THE ROOT - BIOLUMINESCENT CAVERN" or might it vary to "INT. ROOT TUNNELS" or "INT. ORGANIC UNDERBELLY"? Different headings = different location entries in breakdown = visual inconsistency.

2. **Description drift:** Even with the same heading, prose descriptions may drift across batches. Episode 16's description of The Root may emphasize bioluminescence while episode 25 emphasizes organic walls. Both are "correct" but generate visually different frames.

3. **Accumulated damage:** If something happens to a location (explosion, structural damage), that needs to persist in subsequent appearances.

**Potential solutions:**
- [ ] Add a **location bible** section to treatment.md or ORCHESTRATION.md that locks canonical descriptions
- [ ] Add a location consistency check to the generation pipeline (similar to character voice checks)
- [ ] Breakdown should track "location first described in ep X" and flag description drift in later episodes
- [ ] Scene heading normalization in the extraction script (strip time-of-day, normalize capitalization)

### Partial Extraction vs Full

When running on a subset (eps 1-5 of 60), the breakdown contains:
- State changes from characters.md that reference future episodes (ep 10, 20, 30, 45)
- Wardrobe phases covering the full 1-60 range
- But only 5 episodes of actual content

The validator flags this as "state change at ep 10 but last appearance is ep 5." This is correct behavior for the validator but creates noise for partial runs.

**Options:**
- [ ] Add `--partial` flag to validator that suppresses warnings about future episodes
- [ ] Only include state changes within the processed episode range
- [ ] Keep current behavior (warnings are informative, not blocking)

---

## Process Improvements

### What Worked Well

- Extraction script correctly identified all characters, locations, and dialogue counts
- Schema is well-designed for downstream consumers
- Validation gate catches real issues
- Claude enrichment added genuine value (hair/makeup, color palettes, corrected wardrobe, false positive removal)

### What Needs Work

1. ~~**SFX regex is noisy.**~~ ✓ FIXED — word boundaries + exclusion patterns + keyword pruning
2. ~~**Props detection is noisy.**~~ ✓ FIXED — pre-scan + individual word matching + VFX dedup
3. ~~**Wardrobe source is wrong.**~~ ✓ FIXED — marked for enrichment, preserves episode ranges
4. **No crowd/extras support.** Schema gap for a common production need.
5. **Location consistency not tracked.** No mechanism to ensure visual consistency when locations recur.

### Recommended Next Steps

1. **Short term:** ~~Fix P1 script issues~~ ✓ DONE. Run next breakdown (full 60 eps or next batch) to validate fixes at scale.
2. **Medium term:** Add crowds to schema. Add location consistency tracking. Consider location bible in ORCHESTRATION.md.
3. **Long term:** Evaluate whether script + enrichment continues to outperform Claude-only after a full series run.

---

*Created: 2026-01-31*
*First run: Leviathan eps 1-5*
*Script fixes applied: 2026-01-31 — P1 props, P1 SFX, P2 wardrobe, P2 specialty shots all resolved*
## Future: Visual Asset Pre-Populator Editor

Build an editor.html (like shotlist_editor, revision_editor) that pre-populates character sheets and visual assets for Midjourney/Nana-Banana-Pro iteration. Should load from breakdown.json + visual_bible.md, present character designs with prompt fields, and allow iterative refinement before final asset generation. Similar workflow to existing editors but focused on character design iteration.
## Future: Visual Asset Pre-Populator Editor

**Context:** After /breakdown extracts visual assets, the user needs to build character sheets and other assets in Midjourney/Nana-Banana-Pro. Currently manual.

**Idea:** Build an HTML editor (like breakdown_editor.html, shotlist_editor.html, revision_editor.html) that:
- Pre-populates from breakdown.json + visual_bible.md
- Shows character reference images, HEX palettes, lens packages
- Provides copy-ready prompts for Midjourney/Nana-Banana-Pro
- Allows iteration: tweak prompt → regenerate → approve → save
- Tracks which assets are complete vs pending

**Priority:** After current pipeline completion.
**Date noted:** 2026-01-31