# Treatment Format Rules

> **Reference copy.** This is the internal process specification. The user-invocable command lives at `.claude/skills/treatment/SKILL.md`.

> **The treatment is PROSE, not bullets. A document humans can read like a story synopsis.**
> **Numeric values (word counts, ratios):** See `/CONSTANTS.md`

---

## What is a Treatment?

A treatment transforms development notes (`episode_arc.md`) into **flowing prose paragraphs** that serve two purposes:

1. **Human review** — Read all 60 episodes in 15 minutes, spot structural issues
2. **Generator guidance** — Prose conveys intent and tone, not just events

**CRITICAL:** The output is prose paragraphs, NOT enriched bullets.

- ❌ DO NOT keep `- **Event:**`, `- **Cass:**`, `- **Hera:**` structure
- ❌ DO NOT add metadata to existing bullets
- ✅ DO write flowing prose paragraphs
- ✅ DO weave all bullet content INTO the prose
- ✅ DO create a document that reads like a treatment, not a database

---

## treatment.md Format

```markdown
# [PROJECT] — Treatment

> [Logline or thematic statement]

---

## THREAD INDEX

| Thread | Plant | Advances | Payoff | Description |
|--------|-------|----------|--------|-------------|
| Hera Reveal | 3, 7 | 12, 15, 19, 23... | 58-59 | Hidden orchestrator |
[etc.]

---

## ACT I: [ACT NAME] (Episodes 1-15)

### Sequence 1: [Sequence Name] (Episodes 1-7)

---

### Episode 1: "Debt"
**Sequence:** 1 | **Beat:** SETUP | **Hook:** S-VP | **Cliffhanger:** M-CF
**Threads:** [PLANT: Third-Person Tick]
**THE MOMENT:** "Dax is going to need a minute" — his stress response, his humanity
**VOICE SEED:** "Dax is going to need a minute" — third-person self-talk under stress

Dax runs pattern exploits in the lowest level of Tartarus, scraping by on the margins of a system designed to grind people like him into nothing. When a trace puts him on the enforcement grid, he slips away—barely. Alone in the dark afterward, he talks to himself in third person: "Dax is going to need a minute." This is who he is. A survivor. A pattern-reader. Completely alone.

**[CLIFFHANGER: Dax disappears into the dark, talking to no one.]**

---
```

---

## Episode Structure

Each episode has exactly:

1. **Header** — `### Episode N: "Title"`
2. **Metadata line** — Sequence, Beat, Hook, Cliffhanger (pipe-separated)
3. **Threads line** — Thread markers or "None"
4. **THE MOMENT line** — The one image/line/beat that's the emotional payload
5. **VOICE SEED line** — (Episode 1 only) Signature dialogue that sets character idiom
6. **Prose paragraph** — Flowing narrative (word count varies by beat type)
7. **Cliffhanger image** — Specific visual/line to end on (in brackets)

---

## THE MOMENT

Every memorable episode has ONE moment that sticks with you. This is the North Star for generation.

**Format:** `**THE MOMENT:** [specific image/line] — [why it matters]`

**Examples:**
- `**THE MOMENT:** Dax admits "I wanted to say yes" — first vulnerability`
- `**THE MOMENT:** Helios orders two drinks — the smallest gesture, huge for him`
- `**THE MOMENT:** The throne room is empty — everything he climbed for was a lie`

**If the script doesn't nail THE MOMENT, it failed.**

---

## VOICE SEED (Episode 1 Only)

Episode 1 must include a **VOICE SEED**—a specific line of dialogue that establishes the protagonist's idiom. Generators will echo this voice forward through the series.

**Format:** `**VOICE SEED:** "[exact line]" — [what it establishes]`

**Examples:**
- `**VOICE SEED:** "Daddy needs a new pair of lungs" — gambling idiom, gallows humor`
- `**VOICE SEED:** "Dax is going to need a minute" — third-person self-talk, stress response`
- `**VOICE SEED:** "The math doesn't lie. People do." — analytical detachment, trust issues`

**Rules:**
- Must appear in Episode 1 prose paragraph (not just the VOICE SEED line)
- Should feel natural, not forced exposition
- Establishes idiom that can recur without feeling repetitive
- One seed per protagonist (if multiple POV characters, each gets one)

**Voice Seed should demonstrate HUMOR, not just idiom.**
A good voice seed makes the audience smirk. Bad: "Sixty-forty the wire's live."
(That's idiom, not humor.) Good: "Daddy needs a new pair of lungs."
(That's character — crude, funny, reveals worldview.)

**The VOICE SEED is the DNA sample. Generators clone from it.**

---

## Prose Paragraph Guidelines

### Key Episodes (Structural Anchors)

Three episodes carry extra weight and get more words:

| Episode | Function | Word Range | Why |
|---------|----------|------------|-----|
| **1** | Pilot Template | 80-100 | Sets voice, texture, tone for entire series |
| **10** | Paywall Crisis | 70-90 | Free trial ends—must convert viewers to paying |
| **15** | Threshold | 70-90 | Point of no return, end of Act 1 setup |

**Episode 1** is the baseline. Generators read it to understand what the series sounds like. Establish character idiom, world texture, and visual style here—they'll echo forward.

**Episode 10** must end on maximum urgency (see Episode 10 Paywall Rule below).

**Episode 15** is structural, not commercial—the protagonist crosses a line they can't uncross.

---

### Tiered Word Counts by Beat Type

Keep episodes lean but substantive. Target ~3,000-4,000 words total (~50-65 avg per episode). See `/CONSTANTS.md` for canonical values.

| Beat Type | Word Range | Reason |
|-----------|------------|--------|
| SETUP | 40-55 | Establishing, efficient |
| COMPLICATION | 40-55 | Plot mechanics, keep moving |
| CATALYST | 50-70 | Inciting incident matters |
| LOCK-IN | 50-70 | Commitment moment |
| COLLISION | 60-80 | Major confrontation |
| CRISIS | 60-80 | Emotional depth needed |
| REVELATION | 60-80 | Truth needs unpacking |
| CLIMAX | 70-90 | Peak drama, full weight |
| RESOLUTION | 50-70 | Landing the story |

**Note:** Key episodes (1, 10, 15) override beat type word counts.

### Content Rules

- **Voice:** Third person, present tense
- **Include:** What happens + why it matters emotionally
- **Include:** Key dialogue snippets where they land
- **Weave in:** All development notes (Cass recordings, Hera plants, relationship beats)
- **Tone:** Like a treatment a producer would read

### What to Weave Into Prose

| Original Bullet | How It Appears |
|-----------------|----------------|
| `- **Event:** Dax finds...` | First sentences of paragraph |
| `- **Cass:** Recording...` | Woven in: "Her voice: '...'" |
| `- **Hera:** PLANT...` | Described visually, no label |
| `- **Emotional beat:**` | Final sentences, the "why" |
| `- **Relationship:**` | Woven throughout |

---

## Cliffhanger Image

**CRITICAL:** The cliffhanger is the LAST BEAT of the episode. It must describe:
1. The final moment of the prose paragraph — not an earlier event
2. The precarious/revelatory moment the audience is left on
3. What makes them NEED to see the next episode

**The `**[CLIFFHANGER:]**` line IS the final beat.** The prose builds to it, then the cliffhanger line delivers the ending.

**Format:** `**[CLIFFHANGER: The final moment itself]**`

**Structure:**
```
[Prose building to the cliffhanger moment...]

**[CLIFFHANGER: The ending. This IS the final beat.]**
```

**Examples:**

✅ **CORRECT** — Cliffhanger IS the ending:
```
Varek freezes. The most feared collector on the ship, stopped by a sentence. Jinx grabs Kian's arm. "We run. NOW."

**[CLIFFHANGER: They disappear into the dark. Varek's heart restarts behind them.]**
```

❌ **WRONG** — Prose continues past the cliffhanger moment:
```
Kian catches the drone mid-air. He pulls her debt record. "You are expendable." She stares at her counter. Expendable. That's the math.

**[CLIFFHANGER: Kian catches the drone mid-air.]**  ← Prose kept going after this!
```

**The Cliffhanger Test:**
1. Is this the LAST thing that happens in the prose?
2. Is there genuine uncertainty (M) or weight to absorb (A)?
3. Would you swipe up to see what happens next?

This ensures generators know exactly what image to hit, not just "MID-ACTION" or "AFTERMATH."

---

## Cliffhanger Exclusivity Rule

**CRITICAL:** The cliffhanger image OWNS the final beat exclusively. The prose paragraph must:
- Build TO the cliffhanger moment
- STOP BEFORE describing the cliffhanger image
- NEVER repeat, preview, or describe what the cliffhanger will show

The cliffhanger is the EXCLUSIVE domain of the final image. If the prose already describes the moment, the cliffhanger becomes redundant repetition.

**Structure:**
```
[Prose builds tension, describes events leading up to...]

**[CLIFFHANGER: THE final beat happens HERE, not in the prose above.]**
```

**Examples:**

❌ **WRONG — Prose describes the cliffhanger moment:**
```
His eyes snap open. His hand is on her throat—not squeezing, scanning.
"Identify sector. Identify... Era." The first touch is violence.

**[CLIFFHANGER: His hand on her throat. Five hundred years of silence.]**
```
The prose already said "hand on throat" — the cliffhanger just repeats it.

✅ **CORRECT — Prose stops BEFORE the cliffhanger:**
```
His eyes snap open. Something flickers behind them—recognition? Threat?
Before she can move—

**[CLIFFHANGER: His hand on her throat. Five hundred years of silence.]**
```
The prose builds to "before she can move" — the cliffhanger OWNS "hand on throat."

✅ **CORRECT — Prose leads, cliffhanger lands:**
```
Varek freezes. The most feared collector on the ship, stopped by a sentence.
Jinx grabs Kian's arm.

**[CLIFFHANGER: They disappear into the dark. Varek's heart restarts behind them.]**
```
The prose stops at "grabs arm" — the cliffhanger owns the escape and Varek's restart.

**The Exclusivity Test:**
- Read the cliffhanger line
- Search the prose paragraph for ANY of those words/images
- If you find them: REWRITE — the prose went too far

---

## Metadata Format

One line, pipe-separated, using **subtype codes** from Appendix A:

```
**Sequence:** N | **Beat:** TYPE | **Hook:** S-CO | **Cliffhanger:** M-PT
```

Subtypes give the generator specific direction about HOW the episode opens and closes — not just SILENT vs DIALOGUE but *what kind* of silent, *what kind* of mid-action.

### Beat Types

| Beat Type | Function |
|-----------|----------|
| SETUP | Establish world, character, status quo |
| CATALYST | Inciting incident, world intrusion |
| LOCK-IN | Point of no return, commitment |
| COMPLICATION | New obstacle, plan disruption |
| COLLISION | Major confrontation, thesis vs antithesis |
| CRISIS | All is lost, darkest moment |
| REVELATION | Truth uncovered |
| CLIMAX | Final confrontation, choice made |
| RESOLUTION | New equilibrium, aftermath |

### Hook Types (Subtypes from Appendix A)

**Silent hooks (S-*) — Target: 70-85%**

| Code | Subtype | Description |
|------|---------|-------------|
| S-VP | Visual Punch | Pure image, no context needed |
| S-SF | Sound First | Audio before visual reveals source |
| S-UI | UI Alert | Diegetic interface warning |
| S-CO | Continuation | Pick up mid-action from last cliffhanger |
| S-DE | Detail | Close-up on significant object |
| S-CT | Contrast | Peaceful image, then shattered |
| S-PV | POV | We see through character's eyes |

**Dialogue hooks (D-*) — Target: 15-30%**

| Code | Subtype | Description |
|------|---------|-------------|
| D-PI | Pattern Interrupt | One line, then visual context |
| D-QU | Question | Opens with unanswered question |
| D-DC | Declaration | Statement that reframes everything |
| D-MC | Mid-Conversation | Drop into dialogue already happening |

### Cliffhanger Types (Subtypes from Appendix A)

**Mid-Action (M-*) — Target: 70-85%**

| Code | Subtype | Description |
|------|---------|-------------|
| M-PT | Physical Threat | Grip, fall, wound, trap, collision |
| M-CT | Countdown | Timer, ultimatum, decay |
| M-CH | Choice | Fork, sacrifice, gamble |
| M-PU | Pursuit | Chase in progress, escape uncertain |
| M-CF | Confrontation | Face-to-face, outcome uncertain |

**Aftermath (A-*) — Target: 15-30%**

| Code | Subtype | Description |
|------|---------|-------------|
| A-RE | Revelation | Identity, history, the lie exposed |
| A-CO | Consequence | Irreversible happened, cut before fallout |
| A-PS | Power Shift | Betrayal, leverage revealed |
| A-SI | Silence | Consequence lands, character absorbs |
| A-CT | Cost | Price of victory becomes clear |
| A-DE | Decision | Choice made, implications settling |

### Pattern Variety

- **Main category:** Max 3 consecutive same type (SILENT/DIALOGUE or MID-ACTION/AFTERMATH)
- **Subtype:** Max 3 consecutive same subtype (e.g., no 4x S-CO in a row)
- Vary subtypes within categories for genuine audience variety

### First 10 Episodes Rule (Pilot Window)

**Critical:** The first 10 episodes must hook the audience. All cliffhangers in Ep 1-10 should be MID-ACTION (or REVELATION-level tension). This overrides the pattern variety rule for the opening.

- Ep 1-10: All MID-ACTION cliffhangers allowed (no pattern variety penalty)
- Ep 11+: Standard pattern variety applies (max 3 consecutive same type; see CONSTANTS.md)
- SILENT hooks are fine throughout (they resolve the previous cliffhanger)

### Episode 10 Paywall Rule

**Critical:** Episode 10 is typically a paywall moment (free trial ends). The cliffhanger MUST have maximum urgency—not emotional stillness, but emotional crisis INTO physical danger.

**Pattern:** Emotional beat THEN immediate threat.
- ✅ "He says her name for the first time. Then his systems start failing—he drained himself to save her."
- ✅ "She finally trusts him. Then the dead zone's shielding collapses around them."
- ❌ "They sit in silence. Neither knows what to say." (No urgency)

**The Ep 10 cliffhanger must make viewers NEED to know what happens next—not just want to.**

---

## Thread Markers

```
**Threads:** [PLANT: Thread Name], [ADVANCE: Thread Name]
```

Or if no threads: `**Threads:** None`

| Marker | Meaning |
|--------|---------|
| PLANT | First appearance, subtle |
| ADVANCE | Thread progresses |
| PAYOFF | Thread pays off |

**All thread names must appear in the THREAD INDEX.**

---

## Complete Episode Example

**INPUT (episode_arc.md bullets):**
```markdown
**Ep 12: "Temptation"**
- **Event:** Apollo offers Dax a shortcut. A door opened. A path cleared. "Let me help you see."
- **Cass:** Not present.
- **Hera:** PLANT — Apollo glances off-screen before making the offer. Just for a moment. (He's checking with her.)
- **Emotional beat:** FIRST VULNERABILITY — Later, Dax admits to Helios: "I wanted to say yes."
- **Relationship:** Helios doesn't judge. Just orders another drink. "That's how it starts."
```

**OUTPUT (treatment.md prose):**
```markdown
### Episode 12: "Temptation"
**Sequence:** 2 | **Beat:** COMPLICATION | **Hook:** D-DC | **Cliffhanger:** A-SI
**Threads:** [ADVANCE: Hera Reveal]
**THE MOMENT:** Dax admits "I wanted to say yes" — first vulnerability

Apollo offers a shortcut. A door opened, a path cleared. "Let me help you see." Before making the offer, Apollo glances off-screen—just for a moment, checking with someone we haven't learned to notice yet. Dax refuses, but later, alone with Helios, the truth comes out: "I wanted to say yes." It's the first time he's admitted weakness to anyone. Helios doesn't judge. He just orders another drink. "That's how it starts."

**[CLIFFHANGER: Helios stares at his drink. He's seen this before.]**
```

**Notice:** No bullets. All information woven into flowing prose. THE MOMENT identified. Cliffhanger image specific.

---

## Validation Rules

### Hard Gates

| Check | Requirement |
|-------|-------------|
| Coverage | All 60 episodes present |
| Metadata | Each episode has Sequence, Beat, Hook, Cliffhanger |
| THE MOMENT | Each episode identifies its key moment |
| VOICE SEED | Episode 1 has VOICE SEED line |
| Key episodes | Ep 1 ≥80 words, Ep 10/15 ≥70 words |
| **Total word count** | **3000-4000 words (~15-20 min read)** |
| Cliffhanger image | Each episode ends with bracketed cliffhanger |
| Thread coherence | All markers reference THREAD INDEX |
| All threads resolved | Every PLANT has a PAYOFF |
| Hook ratio | 70-85% SILENT (per CONSTANTS.md) |
| Cliffhanger ratio | 70-85% MID-ACTION (per CONSTANTS.md) |
| Pattern variety | No 4+ consecutive same type (Ep 11+; Ep 1-10 exempt) |
| First 10 intense | Ep 1-10 should all be MID-ACTION cliffhangers |
| Ep 10 urgency | Cliffhanger contains physical danger/threat element |

### Soft Flags (For Plussing)

| Flag | Trigger |
|------|---------|
| Thin prose | Under minimum word count for beat type |
| Bloated prose | Over maximum word count for beat type |
| Vague language | "tensions rise", "things escalate", "stakes increase" |
| Weak MOMENT | Generic or plot-focused instead of emotional |
| Beat repetition | 4+ consecutive episodes with same beat type |
| No escalation | 3+ episodes with no stakes change |
| **Continuity flags** | MID-ACTION cliffhanger → DIALOGUE hook (may lose tension) |

---

## Transformation Process

When converting `episode_arc.md` → `treatment.md`:

1. **Copy Thread Index** directly
2. **For each episode:**
   - Write metadata line (Sequence, Beat, Hook, Cliffhanger)
   - Add thread markers
   - Identify THE MOMENT (the one beat that matters most)
   - Write prose paragraph weaving ALL bullet content
   - End with specific cliffhanger image
3. **Verify** word counts match beat type requirements

Note: `episode_arc.md` remains in `/scripting/bible/` as reference. Treatment is created FROM it, not replacing it.

---

## Quick Reference

```
OUTPUT:           Prose paragraphs, NOT bullets
METADATA:         One line: Sequence | Beat | Hook (subtype) | Cliffhanger (subtype)
THE MOMENT:       One image/line per episode — the emotional payload
VOICE SEED:       Episode 1 only — signature dialogue that sets idiom
KEY EPISODES:     Ep 1 (80-100), Ep 10 (70-90), Ep 15 (70-90)
WORD COUNTS:      40-55 (regular) → 70-90 (climax)
TOTAL LENGTH:     3000-4000 words (~15-20 min read) — HARD GATE
CLIFFHANGER:      End with bracketed specific image
THREADS:          [PLANT: X], [ADVANCE: X], [PAYOFF: X]
HOOK TARGET:      70-85% SILENT (per CONSTANTS.md)
CLIFF TARGET:     70-85% MID-ACTION (per CONSTANTS.md)
SUBTYPE VARIETY:  Max 3 consecutive same subtype (e.g., no 4x S-CO)
CONTINUITY:       MID-ACTION cliff → SILENT hook (resolve visually)
```

---

## Batch Generation Workflow

**Why Batches:** Generating all 60 episodes at once leads to context overflow and uncontrolled drift. Batch generation enables incremental validation and context management.

### Batch Structure

| Batch | Episodes | Word Target |
|-------|----------|-------------|
| 1 | 1-10 | ~550 words |
| 2 | 11-20 | ~550 words |
| 3 | 21-30 | ~550 words |
| 4 | 31-40 | ~550 words |
| 5 | 41-50 | ~550 words |
| 6 | 51-60 | ~550 words |

**Total:** ~3,300 words (within 3,000-4,000 target)

### Batch Workflow

```
1. GENERATE BATCH
   /treatment [project] --batch 1-10

2. VALIDATE BATCH
   python3 /tools/validate_treatment_batch.py ./[project] 1 10

   Hard Gates:
   - All episodes complete (metadata, THE MOMENT, cliffhanger)
   - Word count: 450-650 words per batch
   - No 4+ consecutive same type (max 3 allowed; see CONSTANTS.md)

   If FAIL: Fix issues, re-validate
   If PASS: Proceed

3. CONTEXT CHECKPOINT
   Start new conversation before next batch

4. RESUME
   /treatment [project] --batch 11-20

5. REPEAT through batch 51-60

6. FINAL VALIDATION
   python3 /tools/validate_treatment.py ./[project]
```

### Word Budget Per Episode (Batch Context)

With 10 episodes per batch targeting ~550 words:
- Average: ~55 words per episode
- Key episodes (1, 10, 15): Allow 80-100 words
- Regular episodes: 40-55 words
- Climax episodes: 70-90 words

### Context Management Protocol

**Between batches:**
1. Output checkpoint message: `TREATMENT BATCH N COMPLETE`
2. User starts new conversation
3. New session loads: treatment SKILL, existing treatment.md, episode_arc.md for next batch
4. Read last 2 completed episodes for voice continuity
5. Continue generation

**Why this matters:**
- Prevents context overflow during 60-episode generation
- Enables incremental quality control
- Allows ratio correction between batches if drifting from targets

---

---

## Close Read Pass

After validation passes (or standalone via `--close-read`), a close read pass checks treatment-level continuity. This catches issues that are 10x cheaper to fix here than after 60 episodes are generated.

**Adapted from:** Script Doctor Phase 4 (close read) — same methodology, applied upstream.

### What It Checks

| Category | What It Catches |
|----------|-----------------|
| **Cliffhanger → Hook Logic** | MID-ACTION cliff → DIALOGUE hook undercuts tension. The hook of ep N+1 must logically follow the cliffhanger of ep N. |
| **Spatial Continuity** | Characters can't teleport between locations. If ep N ends at Location A, ep N+1 must start there or account for travel. |
| **Physical Consistency** | Objects, injuries, abilities persist across episodes. Lost limbs stay lost. Given objects stay present. |
| **Motivation Grounding** | Major character decisions need visible reasons. No unmotivated reversals or leaps. |
| **Thread Integrity** | Every PLANT has a PAYOFF. No orphaned plants or surprise payoffs. Thread markers match prose content. |

### When It Runs

| Mode | Close Read? |
|------|-------------|
| `/treatment [project]` (full) | Yes — final phase after validation |
| `/treatment [project] --close-read` | Yes — standalone on existing treatment |
| `/treatment [project] --batch N-M` | No — run after all batches complete |
| `/treatment [project] --validate-only` | No |
| `/treatment [project] --plus [N,N,N]` | No |

### Output

Produces a numbered report (CR-001, CR-002...) with:
- Category, affected episodes, specific issue
- Recommended fix (type swap, prose edit, thread marker addition)
- Auto-fixable vs manual-fix classification

After fixes: re-runs `validate_treatment.py` to confirm no regressions.

**Full close read protocol:** See `/agents/treatment_agent.md` → "Workflow: Close Read Pass"

---

*This skill is READ-ONLY reference. Project-specific content lives in `/[project]/treatment.md`.*