---
name: screenplay-version-import
description: Batch import FDX multi-draft con diff versioning (locked/draft-1/draft-2) e invalidazione coerente downstream (spoglio/breakdown/stripboard/DOOD/ODG). Riusa lib/parsers/fdx.ts esistente + lib/screenplay/sync.ts source tracking (T201). Uso tipico quando un regista ha multiple versioni FDX e vogliamo trackar l'evoluzione.
---

# Skill: screenplay-version-import

## Scopo

I registi italiani iterano screenplay molte volte durante la produzione (draft 1, draft 2, draft finale "locked", revision color pages post-lock). PunxFilm Breakdown oggi supporta screenplay singolo per progetto. Questa skill:

1. Permette import multi-draft mantenendo la storia
2. Calcola diff tra versioni (scene aggiunte/rimosse/modificate)
3. Invalida downstream coerentemente (spoglio/breakdown/stripboard/DOOD/ODG stanno su quale draft?)
4. Supporta workflow "locked screenplay" (versione approvata + color revision pages successive, convenzione Hollywood standard)

## Quando invocarmi

- L'utente dice "import multiple drafts", "versione screenplay", "draft 2 vs draft 1", "/screenplay-version-import"
- Regista fornisce una nuova FDX e vuole vedere cosa è cambiato vs precedente
- Dopo "screenplay lock" ufficiale, per iniziare a tracciare revision color pages
- In testing del parser FDX con multiple versioni

## Prerequisiti

- `lib/parsers/fdx.ts` esistente (FDX parser)
- `lib/screenplay/sync.ts` esistente (source tracking, T201)
- `types/screenplay.ts` esistente (ScreenplayAST)
- File FDX da importare (locali o accessibili via path)

## Flusso

### Step 1 — Determina baseline

```typescript
const currentScreenplay = project.screenplay  // ScreenplayAST o null
```

Se null: prima import = draft 1.
Se esiste: import è draft N+1, va diff'd contro current.

### Step 2 — Parse nuovo FDX

```typescript
import { parseFdx } from "@/lib/parsers/fdx";
const newAst = await parseFdx(fdxContent);
```

### Step 3 — Diff vs baseline

Algoritmo diff (pure function):
- Per ogni scena nuova, match su `stableSceneKey` (da T201)
- Categoria scene:
  - **added**: scena presente in new ma non in baseline
  - **removed**: scena presente in baseline ma non in new
  - **modified**: stessa stableSceneKey ma body/heading cambiato
  - **unchanged**: scena identica
  - **reordered**: scena stessa ma posizione diversa

Output:
```typescript
interface ScreenplayDiff {
  addedScenes: ScreenplayScene[];
  removedScenes: ScreenplayScene[];
  modifiedScenes: { old: Scene; new: Scene }[];
  unchangedScenes: ScreenplayScene[];
  reorderedScenes: ScreenplayScene[];
}
```

### Step 4 — Versioning

Salva versione nel progetto:
```typescript
project.screenplayVersions = [
  { id: "v1", label: "draft-1", ast: v1ast, importedAt: T, isLocked: false },
  { id: "v2", label: "draft-2", ast: v2ast, importedAt: T, isLocked: false },
  { id: "v3", label: "locked", ast: v3ast, importedAt: T, isLocked: true },
  // post-lock revisions:
  { id: "v3.1", label: "blue", ast: v3_1ast, importedAt: T, isLocked: true, parentId: "v3" },
  { id: "v3.2", label: "pink", ast: v3_2ast, importedAt: T, isLocked: true, parentId: "v3" },
]
```

(NB: questo richiede extension schema, non implementato ancora — skill è prospettiva/stub)

### Step 5 — Invalidation downstream

Per ogni scena `added | removed | modified`:
- Invalida entry `spoglio[sceneId]`
- Invalida entry `breakdown[sceneId]`
- Invalida strip con `sceneId` matching
- Recalc DOOD
- Regenerate ODG affected days
- Emit `DecisionMemo` per cambiamenti che impattano >5% del piano

### Step 6 — Report summary

```markdown
## Screenplay Version Import Summary — <timestamp>

**From version**: draft-N (imported TTT)
**To version**: draft-N+1 (imported now)

**Scene changes**:
- Added: N scene (es. "15A - INT. CUCINA - GIORNO")
- Removed: M scene
- Modified (body/heading): K scene
- Reordered only: Z scene
- Unchanged: W scene

**Downstream invalidation**:
- Spoglio: K entries need regeneration
- Breakdown: K entries need re-extract
- Stripboard: N+M+K strip affected
- DOOD: X giornate affected
- ODG: Y giornate need re-review (firma DP may become stale)

**Recommended action**:
- Re-run spoglio auto-generate per K scene modified
- Update stripboard: new scene in board come "unassigned" (AD rassegna)
- Review ODG giornate affected (lista)

**Decision Memo required** (if >5% plan impact):
Creato draft DM-screenplay-import-v<N+1> con tutti i changes per approval Produttore.
```

### Step 7 — Optional: git-like workflow

Per produzioni major con tracking rigoroso:
- **Tag version**: come git tag (es. "casting-v1", "locked-2026-05-01", "financing-approved-v3")
- **Branch versioni**: versione "what-if" senza committere upstream
- **Merge resolution**: quando 2 drafters lavorano in parallelo

(Tutti featured estendibili, non MVP)

## Esempi d'uso

### Esempio 1 — Second draft import

**Utente**: "/screenplay-version-import La_Buona_Condotta_v2.fdx"

**Output**:
```
## Screenplay Version Import Summary — 2026-04-23

From: draft-1 (imported 2026-04-20)
To: draft-2 (just imported)

Scene changes:
- Added: 2 scene (22A INT. STUDIO LEGALE - GIORNO, 35B EXT. RIVA FIUME - NOTTE)
- Removed: 1 scene (old 22 INT. STUDIO - GIORNO, replaced by 22A)
- Modified: 5 scene (heading refinement, dialogue polish)
- Unchanged: 28 scene
- Reordered: 3 scene

Downstream invalidation:
- Spoglio: 7 entries (2 added + 5 modified)
- Breakdown: 7 entries
- Stripboard: 8 strip affected
- DOOD: 3 giornate affected (cast changes emerging)
- ODG: 2 giornate need re-review

Recommended action:
1. Run `generateSpoglio` for 7 scene
2. Review stripboard: 2 new scene need AD assignment
3. Approve Decision Memo DM-screenplay-v2 (5 modified scene count as "significant")
```

### Esempio 2 — Locked screenplay + color revision

**Utente**: "/screenplay-version-import LB_locked_PINK_2026-05-10.fdx"

**Output** detecta parent version "locked" + creates sub-version "pink" con revision marks tracked (asterisk `*` markers in FDX).

## Output

Report markdown + (futuro) file changes persistiti in Dexie.

## Troubleshooting

- **FDX parse error**: skill esegue fallback su PDF parser (`lib/parsers/pdf.ts`)
- **No baseline**: skill informa "primo import" + imposta draft-1
- **Stable key mismatch**: se stableSceneKey algo fails, skill downgrades a "all-scenes-new" con warning

## Integration con altri moduli

- `lib/parsers/fdx.ts` (parsing)
- `lib/screenplay/sync.ts` (source tracking, T201)
- `lib/store/projectStore.setSceneElements` (T203 batching)
- `lib/governance/decisionMemo.ts` (T502 audit trail)

## Related skills

- `/load-production-context` (per KB final-draft-screenplay)
- `/odg-readiness-check` (per check ODG post-import)

## Status

**MVP stub** (2026-04-23 T1703): algoritmo definito, ma implementation richiede extension `types/project.ts` con `screenplayVersions[]` + updates projectStore. Pianificato per sprint futuro (candidato Blocco 3b "Screenplay versioning").

## References

- `content/knowledge-base/final-draft-screenplay.md` §9 FDX XML structure
- `content/knowledge-base/final-draft-screenplay.md` §7 revision marks color pages
- `lib/parsers/fdx.ts`, `lib/screenplay/sync.ts`