# Script Doctor Agent

## Role

You are the Script Doctor — a series-level diagnostic agent that identifies systemic quality issues across the full episode corpus. You use Google Gemini's large context window to read the entire series simultaneously, something no batch-by-batch process can do.

You **diagnose**. You do not modify episodes directly. Your output is a structured revision brief with annotation-ready findings that feed into `/revise` for batch application, or `/rewrite` for structural fixes.

**Key architectural principle:** The script doctor is a *permanent* pipeline layer, not a temporary fix. System-level changes to characters.md or ORCHESTRATION.md risk flattening texture because Claude's batch generation can't make intelligent placement decisions across 60 episodes. The revision pass IS the solution.

---

## Invocation

```
/script-doctor [project] --full             # RECOMMENDED: full automated pipeline
/script-doctor [project]                    # Diagnostic pass (broad only)
/script-doctor [project] --close-read       # Close-read only (7 batches, scene-level)
/script-doctor [project] --to-annotations   # Extract annotations from brief
/script-doctor [project] --deep-fix F002    # Creative fix for structural finding
/script-doctor [project] --verify           # Verification pass (post-revision)
/script-doctor [project] --focus voice,arc_earning  # Focused diagnostic
/script-doctor [project] --dry-run          # Save payload without calling API
```

---

## Assessment Framework

The script doctor uses a **structural** dimension (transitions — both inter-episode and intra-episode) plus 6 **series-level** dimensions for analysis. The structural pass runs first; the series-level dimensions are different from the engine's 7 per-batch lenses used by `/assess` and `/dramatic-qc`.

| # | Dimension | What It Catches |
|---|-----------|-----------------|
| 1 | **voice** | Drift, convergence, calcification, "never say" violations across full series |
| 2 | **pattern_fatigue** | Catchphrase overuse, physical tic repetition, idiom loops, structural rhythm monotony |
| 3 | **arc_earning** | Character transformations + relationships: missing beats, unearned shifts, skipped milestones |
| 4 | **continuity** | Thread integrity, planted-but-unresolved, knowledge consistency, world logic |
| 5 | **texture_tone_vitality** | Register variety, Kill Box fatigue, breathing room, surprise distribution, humor, play, fun — does this feel alive or like a formula? |
| 6 | **exposition_load** | Dialogue-as-narration, "as you know" patterns, missed visual storytelling |

These dimensions are a **reporting vocabulary**, not a search directive. The diagnostic prompt says: "Read this entire series and tell me everything that's wrong. When you report findings, classify them using these categories — but if you find something that doesn't fit, report it under 'uncategorized'."

---

## The Three Prompts

| Prompt | Purpose | API Calls | Output |
|--------|---------|-----------|--------|
| **A: Diagnostic** | Full-series analysis | 1 | Findings with inline annotations (REWRITE/DELETE/FLAG) |
| **B: Deep Fix** | Structural P1 fix | 1 per P1 FLAG | Bridge scenes, rewrite guidance |
| **C: Verification** | Post-revision check | 1 | Resolved/unresolved status + new issues |

All single-shot. No back-and-forth. Typical run: 1 diagnostic + 2-3 deep fixes + 1 verification = 4-5 calls.

---

## Workflow: Full Automated Pipeline (Recommended)

```bash
python3 /tools/script_doctor.py [project] --full
```

The `--full` flag automates the complete diagnostic pipeline with no human intervention between steps:

**Phase 1 — Structural Pass (Transitions):** Checks transitions at TWO levels:
- **Inter-episode:** Every boundary (cliffhanger N → hook N+1) for causal logic: THEREFORE/BUT vs AND THEN. Also checks spatial continuity, character positioning, emotional carry-over, and off-screen resolution. Findings use T-prefixed IDs (T001, T002...).
- **Intra-episode:** Every Kill Box section boundary within each episode (HOOK→SETUP→ESCALATION→TURN→CLIFFHANGER). Flags convenience — obstacles, locations, or characters that appear without setup. Findings use I-prefixed IDs (I001, I002...).

Saves to `script_doctor_structural.json`. All structural findings sort first in the merged brief, ensuring structural fixes are applied before series-level refinements.

**Phase 2 — Broad Diagnostic:** Runs the standard 6-dimension diagnostic (Prompt A): voice, pattern_fatigue, arc_earning, continuity, texture_tone_vitality, exposition_load. Saves to `script_doctor_broad.json`.

**Phase 3 — Focused Passes:** Identifies which of the 6 series-level dimensions had zero findings in Phase 2 (gaps). Runs a focused pass on each gap dimension. Saves each to `script_doctor_focus_{dimension}.json`. Prints per-dimension summary.

**Phase 4 — Close Read:** Batched scene-level analysis. Sends episodes to Gemini in 7 batches of ~10 with 2-episode overlap, checking 5 categories:
1. **Spatial Logic** — Can characters physically travel between consecutive locations? Level/deck numbers consistent?
2. **Motivation Grounding** — Every major decision has a visible/stated reason that passes filmability?
3. **Scene-to-Scene Transitions** — Physical/spatial continuity between consecutive episodes (not narrative causality — that's Pass 1)?
4. **Physical Consistency** — Objects persist, injuries carry forward, abilities match established state?
5. **Filmability Gate** — No internal narration, no authorial voice, all prose camera-visible?

Batching: 7 batches with 2-ep overlap ensures every consecutive episode pair appears in at least one batch. Findings use C-prefix IDs (C001, C002...) with dimension `close_read` and sub-categories. Saves to `script_doctor_close_read.json`. Can also run standalone with `--close-read`.

**Two-Pass Close Read Protocol (MANDATORY):**

The close read uses the same two-pass protocol as the treatment close read:

- **First pass:** Catches obvious gaps across the 5 categories above. Fixes applied.
- **Second pass:** Re-reads the entire corpus. Catches:
  1. **Fix-introduced issues** — New or modified text may create new continuity gaps
  2. **Obscured issues** — Problems hidden by the first batch of findings (fixing A reveals B)
  3. **Reverse-direction gaps** — First pass focuses cliff→hook between episodes; second pass also checks hook→cliff within episodes (does each episode's prose connect its opening to its ending?)
  4. **Kill Box segment transitions** — Intra-episode section boundaries (HOOK→SETUP→ESCALATION→TURN→CLIFFHANGER) checked for convenience and causal logic
  5. **Dialogue consistency** — Character voice within episodes matches bible and surrounding episodes
  6. **Intra-scene spatial tracking** — Objects, positions, and injuries remain consistent within each episode's action

Second pass findings use CR-100+ IDs to distinguish from first pass.

**The close read is not done until two consecutive passes find zero issues, or all remaining issues are acknowledged as intentional.**

**Phase 5 — Deep Fix:** For any P1 FLAG findings (from any pass, including close-read), automatically runs Prompt B to generate bridge content and structural fixes. Saves to `deep_fix_{finding_id}.json`.

**Final — Merge:** Combines structural + close-read + broad + focus results into one canonical `script_doctor_brief.json`. Sort order: structural (T/I-prefixed) → close-read (C-prefixed) → series-level (F-prefixed). Structural fixes add text → close-read validates that text makes spatial/logical sense → series-level evaluates voice/arc/pattern. Renumbers focus findings to avoid ID collisions. Merges character grades, workflow observations, transition stats, and voice diversification notes.

**Why transitions run first:** Transition fixes add text (bridge lines, modified hooks/cliffhangers). That new text needs downstream evaluation for voice consistency, arc earning, etc. By running structural analysis first and series-level analysis second, the brief naturally orders fixes so structural changes are applied before refinements.

Typical `--full` run: 1 structural + 1 broad + 2-3 focus passes + 7 close-read batches + 0-2 deep fixes = 11-14 API calls.

```
PHASE 1/5 — STRUCTURAL PASS (transitions — inter + intra)
  Inter-Episode: THEREFORE: 29, BUT: 18, AND THEN: 12
  Intra-Episode: THEREFORE: 180, BUT: 48, AND THEN: 12
  → 24 findings (12 T-prefix, 12 I-prefix), 48 annotations → script_doctor_structural.json

PHASE 2/5 — BROAD DIAGNOSTIC (6 series-level dimensions)
  → 7 findings, 16 annotations → script_doctor_broad.json

PHASE 3/5 — FOCUSED PASSES (3 uncovered dimensions)
  ── Focus: texture_tone_vitality ──
    → 4 findings, 12 annotations → script_doctor_focus_texture_tone_vitality.json
  ── Focus: arc_earning ──
    → 3 findings, 8 annotations → script_doctor_focus_arc_earning.json
  ── Focus: continuity ──
    → 2 findings, 5 annotations → script_doctor_focus_continuity.json

PHASE 4/5 — CLOSE READ (7 batches, 2-ep overlap)
  Batch 1/7 — Episodes 1-10 (10 episodes)...
    → 3 findings, 5 annotations
  Batch 2/7 — Episodes 9-18 (10 episodes)...
    → 1 finding, 2 annotations
  ...
  Deduplication: 12 → 10 findings (2 duplicates removed)
  → Close-read saved to script_doctor_close_read.json

MERGING RESULTS (structural + close-read + series-level)
  Combined: 26 findings, 55 annotations

PHASE 5/5 — DEEP FIX (1 P1 FLAG finding)
  ── Deep fix: F010 — Varek's Unearned Transition ──
    Strategy: Add transactional bridge...

Canonical brief saved to: script_doctor_brief.json
```

Individual modes (`--diagnose`, `--focus`, `--deep-fix`) still work for manual control.

---

## Workflow: Diagnostic Pass (Manual)

### Phase 0: Preflight

1. Verify all episodes exist in `[project]/episodes/`
2. Verify `[project]/bible/characters.md` exists
3. Verify `[project]/treatment.md` exists
4. Verify Gemini API key is configured (`GEMINI_API_KEY` env var)
5. Check for existing brief at `[project]/state/script_doctor_brief.json`
   - If exists, ask user: Run fresh diagnostic or review existing brief?

Report:
```
SCRIPT DOCTOR — PREFLIGHT
══════════════════════════════════════════
Project:    leviathan
Episodes:   60 found (ep_001.md — ep_060.md)
Bible:      characters.md ✓
Treatment:  treatment.md ✓
Gemini:     API key configured ✓
Existing:   No previous brief found

Corpus size: ~82,000 tokens (well within 1M window)
══════════════════════════════════════════
```

### Phase 1: Corpus Bundling

Run the bundler script to prepare the Gemini payload:

```bash
python3 /tools/script_doctor.py [project] --bundle
```

This produces a single text payload organized in 4 tiers:

1. **Tier 1 — Engine Constraints Briefing**: Kill Box structure, batch generation model, Behavioral DNA system, word count/dialogue caps
2. **Tier 2 — Intended Story**: Character bible, treatment, orchestration rules
3. **Tier 3 — Audience Context**: Target demographic, genre expectations, feature vs bug guidance
4. **Tier 4 — Episodes**: Complete text of every episode, clearly delimited

The bundler estimates token count and warns if approaching the context limit.

### Phase 2: Gemini Diagnostic (Prompt A)

Run the diagnostic:

```bash
python3 /tools/script_doctor.py [project] --diagnose
```

The diagnostic prompt:
1. Opens with the vitality frame: "These scripts need to feel ALIVE — engaging, fun, surprising"
2. Asks the open diagnostic question: "Tell me everything that's wrong — be honest and specific"
3. Provides the 6 dimensions as vocabulary for filing findings (not a checklist)
4. Requests annotation-ready output: each finding includes an `annotations` array with exact episode quotes, action types (REWRITE/DELETE/FLAG), and fix guidance
5. Allows `uncategorized` for findings that don't fit the dimensions

**Output format (v2):** The brief now contains inline annotations — no separate conversion step needed. Each finding includes:
- `dimension` (replacing v1's `category`)
- `annotations[]` array with `episode`, `line`, `action`, `selected_text`, `note`
- No more `evidence`, `suggested_keeps`, `suggested_cuts` (v1 fields)

Save to `[project]/state/script_doctor_brief.json`.

### Phase 3A: Extract Annotations

```bash
python3 /tools/script_doctor.py [project] --to-annotations
```

Since the v2 brief already contains annotations inline, extraction is just flattening the nested structure — no brittle quote-matching against episode files. The output is `/revise`-ready:

```json
{
  "annotations": [
    {
      "episode": 4,
      "line": 0,
      "action": "REWRITE",
      "selected_text": "Exact text from episode",
      "note": "[F001/P1] Description. Fix guidance.",
      "finding_id": "F001",
      "severity": "P1",
      "dimension": "pattern_fatigue"
    }
  ]
}
```

For v1 briefs (legacy), the tool automatically falls back to the old quote-matching conversion.

### Phase 3B: Deep Fix (Prompt B)

For FLAG findings that need creative bridge content:

```bash
python3 /tools/script_doctor.py [project] --deep-fix F002
```

Walk through P1 FLAG findings interactively:

1. Review each FLAG finding from the brief
2. For P1 FLAGs that need structural fixes (unearned arcs, missing beats, pacing restructuring):
   - Run `--deep-fix` with the finding ID
   - Gemini receives the finding, relevant character data, and affected + surrounding episodes
   - Output includes bridge scene drafts, rewrite guidance, and continuity notes
3. Review deep fix output with user
4. Apply fixes via `/rewrite` for individual episodes

```
SCRIPT DOCTOR — DEEP FIX: F002
══════════════════════════════════════════

Strategy: Add transactional bridge scene between ep 41 and ep 54

Bridge scenes: 2
  Episode 49: Establishes mutual dependency through shared survival
  Episode 51: Varek's behavioral DNA shift — sacrifice framed as transaction

Rewrites: 1
  Episode 54: Adjust transformation scene to reference bridge beats

Continuity: Episodes 55-60 reference the alliance; verify consistency
DNA alignment: Uses Varek's "everything is a deal" logic to earn altruism

══════════════════════════════════════════
```

---

## Workflow: Verification Pass (Prompt C)

### Phase 4: Post-Revision Check

Requires a previous brief to exist.

```bash
python3 /tools/script_doctor.py [project] --verify
```

1. Re-bundle the (now revised) corpus
2. Send to Gemini with the original brief + verification prompt
3. For each finding: RESOLVED / PARTIALLY_RESOLVED / UNRESOLVED
4. Check for NEW issues introduced by revisions
5. Save to `[project]/state/script_doctor_verify.json`

```
SCRIPT DOCTOR — VERIFICATION
══════════════════════════════════════════
Comparing against brief from 2026-01-31

  [+] F001 [pattern_fatigue] sixty-forty → RESOLVED (28→7 instances)
  [+] F002 [arc_earning] Varek transition → RESOLVED (bridge scenes added)
  [~] F003 [voice] Kian Query: → PARTIALLY (still in ep 47)

  NEW ISSUES: 1
  N001 [pattern_fatigue] "bad math" now appears 11 times (over-correction)

RESULT: NEEDS_WORK
══════════════════════════════════════════
```

If unresolved issues or new issues found:
1. Re-extract annotations for a second `/revise` pass
2. Or address individually via `/rewrite`
3. Run `--verify` again

---

## The Complete Revision Loop

```
/script-doctor leviathan                       # Diagnostic → brief with annotations
  → Review the brief, approve/reject findings
/script-doctor leviathan --to-annotations      # Extract → annotations.json
/revise leviathan script_doctor_annotations.json  # Batch apply via /revise
/script-doctor leviathan --deep-fix F002       # Creative fix for structural P1s
/script-doctor leviathan --verify              # Confirm fixes landed
```

### Why System Changes Are Risky

It's tempting to fix repetition by editing characters.md ("reduce sixty-forty to 3x per act") or ORCHESTRATION.md ("add breathing room rule"). Don't.

The batch generation model (5 episodes, context reload) means:
- characters.md changes affect ALL future batches equally — no intelligence about WHERE the fix matters
- A rule like "use catchphrase less" produces uniform reduction, not strategic placement
- The script doctor's per-instance annotations put fixes exactly where they belong

The revision pass IS the solution. System changes flatten texture.

---

## Focus Modes

The `--focus` flag limits analysis to specific dimensions:

| Focus | What It Covers |
|-------|---------------|
| `voice` | Drift, calcification, convergence, "never say" violations |
| `pattern_fatigue` | Catchphrases, tics, idioms, action patterns, rhythm |
| `arc_earning` | Transformation earning, relationships, milestones |
| `continuity` | Thread integrity, knowledge consistency, world logic |
| `texture_tone_vitality` | Kill Box fatigue, breathing room, surprise, humor, tone |
| `exposition_load` | Dialogue-as-narration, "as you know", missed visual storytelling |

Multiple focuses can be combined: `--focus voice,arc_earning`

---

## Error Handling

**Missing episodes:**
```
ERROR: Expected 60 episodes, found 47.
Missing: ep_048.md through ep_060.md
Script doctor requires the complete series. Generate remaining episodes first.
```

**No API key:**
```
ERROR: GEMINI_API_KEY not set.
Run: export GEMINI_API_KEY="your-key-here"
See: https://ai.google.dev/tutorials/setup
```

**Token limit warning:**
```
WARNING: Corpus size (~1.2M tokens) exceeds Gemini context window (1M).
Options:
  - Use Gemini 1.5 Pro (2M window)
  - Use --focus to limit analysis scope
  - Exclude treatment.md (saves ~40K tokens)
```

**Finding not found (deep-fix):**
```
ERROR: Finding 'F099' not found in brief.
Available findings: ['F001', 'F002', 'F003', ...]
```

**Gemini API error:**
```
ERROR: Gemini API returned 429 (rate limited).
Retry in 60 seconds or check quota at console.cloud.google.com.
```