---
name: finish
description: Complete post-generation pipeline — script-doctor, revisions, verification, compile. One command from generated episodes to final Fountain output.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Skill
argument-hint: "[project] [--from step | --skip-doctor]"
---

# /finish - Post-Generation Pipeline

Chains all post-generation steps into one autonomous command. Runs script-doctor, extracts annotations, applies revisions, re-validates, verifies, and compiles — never stops to ask.

## Usage

```
/finish [project]                    # Full post-generation pipeline
/finish [project] --from revise     # Resume from revision step
/finish [project] --skip-doctor     # Skip script-doctor, go straight to compile
```

**Examples:**
```
/finish leviathan                    # Full pipeline: doctor → annotations → revise → validate → verify → compile
/finish leviathan --from doctor      # Resume from script-doctor step
/finish leviathan --from revise      # Resume from annotation application
/finish leviathan --from verify      # Resume from verification
/finish leviathan --from compile     # Resume from compilation only
/finish leviathan --skip-doctor      # Skip doctor entirely, compile what exists
```

## Parameters

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `project` | Yes | -- | Project folder name |
| `--from` | No | -- | Resume from specific step: `doctor`, `revise`, `verify`, `compile` |
| `--skip-doctor` | No | false | Skip script-doctor, go straight to compile |

---

## Pipeline Steps

The pipeline executes these steps autonomously in order. **Never stop to ask the user for input.**

### Step 1: Preflight

Verify all prerequisites before starting:

```bash
# Check episodes exist
ls /Users/joeturnerlin/Dropbox/CLAUDE_DATA/recoil/projects/[project]/scripting/episodes/ep_*.md | wc -l

# Check treatment.md exists
test -f /Users/joeturnerlin/Dropbox/CLAUDE_DATA/recoil/projects/[project]/treatment.md

# Check characters.md exists
test -f /Users/joeturnerlin/Dropbox/CLAUDE_DATA/recoil/projects/[project]/scripting/bible/characters.md

# Check Gemini API key is set
test -n "$GEMINI_API_KEY"
```

**Gate:** If any check fails, report what's missing and stop. Do not proceed with a partial corpus.

### Step 2: Script Doctor (Full Diagnostic)

Run the complete multi-pass diagnostic:

```bash
cd /Users/joeturnerlin/CLAUDE_PROJECTS/recoil && PYTHONPATH=. python3 tools/script_doctor.py [project] --full
```

This runs all passes:
- **Structural** (inter + intra episode transitions)
- **Broad** (6 series-level dimensions)
- **Focused** (targeted dimension analysis)
- **Close-read** (scene-level, 7 batches)
- **Deep-fix** (structural P1 fixes)

**Output:** `/Users/joeturnerlin/Dropbox/CLAUDE_DATA/recoil/projects/[project]/_pipeline/state/script_doctor_brief.json`

Report: total findings count, P1/P2/P3 breakdown.

### Step 3: Extract Annotations

Convert the diagnostic brief into actionable annotations:

```bash
cd /Users/joeturnerlin/CLAUDE_PROJECTS/recoil && PYTHONPATH=. python3 tools/script_doctor.py [project] --to-annotations
```

**Output:** `/Users/joeturnerlin/Dropbox/CLAUDE_DATA/recoil/projects/[project]/_pipeline/state/script_doctor_annotations.json`

Report: number of annotations extracted, breakdown by action type (REWRITE/DELETE/FLAG).

### Step 4: Apply Revisions

Apply REWRITE and DELETE annotations automatically. FLAG annotations are logged but not auto-applied (they require `/rewrite` or manual intervention).

```bash
cd /Users/joeturnerlin/CLAUDE_PROJECTS/recoil && PYTHONPATH=. python3 tools/apply_annotations.py [project]
```

**Rules:**
- REWRITE annotations: apply the replacement text automatically
- DELETE annotations: remove the targeted text automatically
- FLAG annotations: log to console but skip — these need manual/creative intervention

Report: number of annotations applied (REWRITE + DELETE), number of FLAGs skipped, episodes modified.

### Step 5: Re-validate All Modified Episodes

Run `episode_metrics.py` on every episode that was modified in Step 4:

```bash
cd /Users/joeturnerlin/CLAUDE_PROJECTS/recoil && PYTHONPATH=. python3 tools/episode_metrics.py /Users/joeturnerlin/Dropbox/CLAUDE_DATA/recoil/projects/[project]/scripting/episodes/ep_XXX.md --json
```

For each modified episode:
1. Run validation
2. Check `is_valid` in output
3. If `false` and word count is out of range:
   - If OVER: trim action description words to fit
   - If UNDER: add sensory detail to action blocks
   - Re-validate (max 3 attempts per episode)
4. If still invalid after 3 attempts, log the episode for manual fix

Report: episodes validated, episodes that needed word count adjustment, episodes that remain invalid.

### Step 6: Verify

Run the verification pass to confirm fixes landed:

```bash
cd /Users/joeturnerlin/CLAUDE_PROJECTS/recoil && PYTHONPATH=. python3 tools/script_doctor.py [project] --verify
```

**This step is informational — do not block compile on verification results.** If issues remain, log them in the final report.

Report: verification result (pass/fail), remaining issues count.

### Step 7: Compile

Produce both clean and metadata Fountain compilations:

```bash
cd /Users/joeturnerlin/CLAUDE_PROJECTS/recoil && PYTHONPATH=. python3 tools/compile_episodes.py [project]
cd /Users/joeturnerlin/CLAUDE_PROJECTS/recoil && PYTHONPATH=. python3 tools/compile_episodes.py [project] --metadata
```

**Output:**
- `/Users/joeturnerlin/Dropbox/CLAUDE_DATA/recoil/projects/[project]/[TITLE]_COMPLETE.fountain` (clean)
- `/Users/joeturnerlin/Dropbox/CLAUDE_DATA/recoil/projects/[project]/[TITLE]_WITH_METADATA.fountain` (with episode titles + cliffhanger callouts)

Report: both file paths and sizes.

---

## Resume Behavior (`--from`)

| `--from` value | Skips | Starts at |
|----------------|-------|-----------|
| `doctor` | Preflight | Step 2 (Script Doctor) |
| `revise` | Preflight, Script Doctor, Extract | Step 4 (Apply Revisions) — assumes annotations already exist |
| `verify` | Steps 1-5 | Step 6 (Verify) |
| `compile` | Steps 1-6 | Step 7 (Compile) |

When resuming, still report the summary for skipped steps as "SKIPPED (resuming from [step])".

---

## Skip Doctor Behavior (`--skip-doctor`)

When `--skip-doctor` is passed:
1. Run Preflight (Step 1)
2. Skip Steps 2-6 entirely
3. Jump straight to Compile (Step 7)

Use this when episodes are already clean and you just need the Fountain output.

---

## Output

Final report includes all step summaries:

```
=====================================================================
FINISH: [PROJECT] — Post-Generation Pipeline Complete
=====================================================================

PREFLIGHT:
  Episodes found: 60
  Treatment: OK
  Characters: OK
  API key: OK

SCRIPT DOCTOR:
  Total findings: 23
  P1: 3 | P2: 12 | P3: 8
  Brief: /Users/joeturnerlin/Dropbox/CLAUDE_DATA/recoil/projects/[project]/_pipeline/state/script_doctor_brief.json

ANNOTATIONS:
  Extracted: 47
  REWRITE: 31 | DELETE: 8 | FLAG: 8

REVISIONS:
  Applied: 39 (31 REWRITE + 8 DELETE)
  Skipped: 8 FLAG (manual review needed)
  Episodes modified: 22

VALIDATION:
  Episodes validated: 22
  Word count adjusted: 4
  Still invalid: 0

VERIFICATION:
  Result: PASS (2 minor issues remaining)

COMPILE:
  Clean:    /Users/joeturnerlin/Dropbox/CLAUDE_DATA/recoil/projects/[project]/[TITLE]_COMPLETE.fountain (142 KB)
  Metadata: /Users/joeturnerlin/Dropbox/CLAUDE_DATA/recoil/projects/[project]/[TITLE]_WITH_METADATA.fountain (148 KB)

=====================================================================
```

---

## Execution

When this skill is invoked:

1. **Parse arguments** for project name and flags (`--from`, `--skip-doctor`)
2. **Set working directory** context: all commands run from the recoil directory with `PYTHONPATH=.`
3. **Execute pipeline steps autonomously** in order, never stopping to ask
4. **Report summary** at each step as it completes
5. **Produce final summary** with all step results

### Step 8: Analysis Suggestion

After all pipeline steps complete, add this to the final report output:

```
ANALYSIS AVAILABLE
Run /analyze-production {project} to extract learnings from this production.
```

Then write a vault task so it surfaces in the next `/morning` briefing:
```bash
VAULT="$HOME/Library/Mobile Documents/iCloud~md~obsidian/Documents/JT-Vault"
echo "- [ ] Run \`/analyze-production {project}\` — production complete, analysis available" >> "$VAULT/01_Tasks/today.md"
```

This does NOT block or prompt. The task surfaces in the next /morning briefing.

---

## Key Rules

- **Runs from the recoil directory** with `PYTHONPATH=.` for all Python commands
- **Script doctor runs with `--full` flag** for complete multi-pass pipeline
- **REWRITE and DELETE annotations are auto-applied** — no user confirmation needed
- **FLAG annotations are logged but NOT auto-applied** — they require `/rewrite` or manual intervention
- **After applying annotations, re-validate every modified episode** with `episode_metrics.py`
- **If validation fails** (word count out of range), attempt up to 3 fixes per episode, then log for manual fix
- **Verification pass is informational** — do not block compile on remaining issues
- **Always produce BOTH compilations** — clean and metadata Fountain files
- **Never stop to ask the user** — this is a fully autonomous pipeline