# APPENDIX A: CLIFFHANGERS & HOOKS TAXONOMY

> **Numeric values (80/20 ratios, etc.):** See `/CONSTANTS.md`

## The Canonical Reference for Episode Endings and Openings

This appendix is the **single source of truth** for cliffhanger and hook types. All other documents (episode_arc, treatment, ORCHESTRATION) must use this taxonomy.

---

## CLIFFHANGERS

### The Two Main Categories

| Category | Code | Ratio | Definition |
|----------|------|-------|------------|
| **Mid-Action** | M | 80% | Cut DURING the crisis, outcome unknown |
| **Aftermath** | A | 20% | Cut AFTER the moment lands, on the weight of it |

**Enforcement:** No 4+ consecutive episodes of the same main category (max 3 allowed; see `CONSTANTS.md`).

---

### Mid-Action Subtypes (M)

Cut DURING the action. The outcome is uncertain. The viewer must swipe to see what happens.

| Subtype | Code | Description | Example |
|---------|------|-------------|---------|
| **Physical Threat** | M-PT | Grip, fall, wound, trap, collision | Hand slipping from ledge |
| **Countdown** | M-CT | Timer, ultimatum, decay | "You have 30 seconds" |
| **Choice** | M-CH | Fork, sacrifice, gamble | Two people need saving, can only reach one |
| **Pursuit** | M-PU | Chase in progress, escape uncertain | Running, hunters closing |
| **Confrontation** | M-CF | Face-to-face, outcome uncertain | Gun raised, finger on trigger |

**Format in episodes:**
```markdown
**CLIFFHANGER TYPE:** Mid-Action (M-PT) - Physical Threat
```

---

### Aftermath Subtypes (A)

Cut AFTER the moment. Let the weight of what happened land. The viewer processes before swiping.

| Subtype | Code | Description | Example |
|---------|------|-------------|---------|
| **Revelation** | A-RE | Identity, history, the lie exposed | "I designed this system" |
| **Consequence** | A-CO | Irreversible happened, cut before full fallout | "PROCESSED" on the screen |
| **Power Shift** | A-PS | Betrayal, leverage revealed, promotion | Ally switches sides |
| **The Silence** | A-SI | Consequence lands, character absorbs | Standing over a body, neither speaks |
| **The Cost** | A-CT | Price of victory becomes clear | Won the battle, lost something precious |
| **The Decision** | A-DE | Choice made, implications settling | She walks away from the cure |

**Format in episodes:**
```markdown
**CLIFFHANGER TYPE:** Aftermath (A-RE) - Revelation
```

---

### Detection Rules (for validation scripts)

**Mid-Action indicators:**
- Last line ends with em-dash (—)
- Last line ends mid-sentence
- Action verbs in present progressive ("falling," "reaching," "running")

**Aftermath indicators:**
- Last line ends with period
- Complete sentence describing settled state
- Weight/silence/stillness language

---

## HOOKS

### The Two Main Categories

| Category | Code | Ratio | Definition |
|----------|------|-------|------------|
| **Silent** | S | 80% | Zero dialogue in first 5 seconds |
| **Dialogue** | D | 20% | Opens with speech |

**Enforcement:** No 4+ consecutive episodes of the same main category (max 3 allowed; see `CONSTANTS.md`).

---

### Silent Hook Subtypes (S)

No dialogue. Pure visual/audio punch.

| Subtype | Code | Description | Example |
|---------|------|-------------|---------|
| **Visual Punch** | S-VP | Pure image, no context needed | ECU: Blood dripping on metal |
| **Sound First** | S-SF | Audio before visual reveals source | SCREAM. Then we see why. |
| **The UI Alert** | S-UI | Diegetic interface warning | .ALERT: BREACH DETECTED |
| **The Continuation** | S-CO | Pick up mid-action from last cliffhanger | Kian's hand still on wire, sparking |
| **The Detail** | S-DE | Close-up on significant object | Fingers grip metal edge |
| **The Contrast** | S-CT | Peaceful image, then shattered | A flower. Then a boot crushes it. |
| **The POV** | S-PV | We see through character's eyes | Kian's tactical overlay, scanning |

**Format in episodes:**
```markdown
**HOOK TYPE:** Silent (S-CO) - Continuation
```

---

### Dialogue Hook Subtypes (D)

Opens with speech. Use sparingly—silent hooks are stronger.

| Subtype | Code | Description | Example |
|---------|------|-------------|---------|
| **Pattern Interrupt** | D-PI | One line, then visual context | "Run." THEN we see what from. |
| **The Question** | D-QU | Opens with unanswered question | "Do you know what they'll do to us?" |
| **The Declaration** | D-DC | Statement that reframes everything | "I designed it. All of it." |
| **Mid-Conversation** | D-MC | Drop into dialogue already happening | "—and that's when I knew we were dead." |

**Format in episodes:**
```markdown
**HOOK TYPE:** Dialogue (D-PI) - Pattern Interrupt
```

---

## MAPPING FROM LEGACY CODES

The episode_arc may use legacy M/C/R/A codes. Map them as follows:

| Legacy Code | New Code | Subtype |
|-------------|----------|---------|
| M (Mid-Action) | M | Use appropriate subtype |
| C (Consequence) | A-CO | Aftermath - Consequence |
| R (Revelation) | A-RE | Aftermath - Revelation |
| A (Aftermath) | A | Use appropriate subtype (often A-SI or A-DE) |

---

## VARIETY TRACKING

### Per-Batch Checklist

Before finalizing each batch of 5 episodes:

- [ ] No 4+ consecutive same main category (max 3 allowed)
- [ ] No 4+ consecutive same subtype
- [ ] At least one Aftermath episode per batch (for 80/20 ratio)
- [ ] Subtypes varied within category

### Series-Wide Distribution

For a 60-episode series:
- **Target Mid-Action:** ~48 episodes (80%)
- **Target Aftermath:** ~12 episodes (20%)

Suggested Aftermath placement (roughly every 5 episodes):
| Range | Suggested Aftermath Episodes |
|-------|------------------------------|
| 1-10 | 4, 6, 8, or 10 |
| 11-20 | 15, 18 |
| 21-30 | 25, 30 |
| 31-40 | 35, 38 |
| 41-50 | 42, 45, 47 |
| 51-60 | 52, 56, 58, 60 |

---

## THE CLIFFHANGER TEST

Before ending any episode, ask:
1. Would you swipe up to see what happens next?
2. Is there genuine uncertainty about outcome (M) OR weight to absorb (A)?
3. Does it feel like an interruption (M) or a gut punch (A)?

---

## TRANSITION LOGIC: CONNECTING CLIFFHANGERS TO HOOKS

### The Rule: THEREFORE / BUT — Never "AND THEN"

Every episode boundary (cliffhanger of Episode N → hook of Episode N+1) must connect via causal logic, not chronological sequence. This is the difference between drama and episodic storytelling.

| Connector | Meaning | Quality |
|-----------|---------|---------|
| **THEREFORE** | The cliffhanger causes or necessitates the next hook. | Good — creates momentum |
| **BUT** | The next hook complicates, subverts, or contradicts expectations from the cliffhanger. | Good — creates surprise |
| **AND THEN** | The next hook merely follows chronologically with no causal link. | **Failure** — breaks immersion |

**Examples:**

| Cliffhanger | Connector | Hook | Verdict |
|-------------|-----------|------|---------|
| Kian's battery dies mid-combat | THEREFORE | Jinx drags his dead chassis to safety | Causal — battery death forces rescue |
| They escape the Collectors | BUT | The person Jinx brings Kian to is terrified of him | Subverts — escape doesn't mean safety |
| Emotional confrontation in compartment | AND THEN | They're at a workshop (how? why?) | **Broken** — audience is disoriented |

### What to Check at Each Boundary

1. **Causal Logic** — Is the connection THEREFORE, BUT, or AND THEN? If AND THEN: the cliffhanger needs a bridge line, or the hook needs to acknowledge how we got here.

2. **Spatial Continuity** — Does the location change make sense? If Episode N ends at Location A and Episode N+1 opens at Location B, could the audience infer how they got there? Or does it feel like teleportation?

3. **Character Positioning** — When a new character appears, do we know why they're there? Were they established as being nearby? Or do they just materialize?

4. **Emotional Continuity** — Does the emotional state carry across? If Episode N ends on a heavy beat, does N+1 acknowledge it? Or does the emotional thread get dropped?

5. **Off-Screen Resolution** — If Episode N ends with an unresolved cliffhanger, does N+1 address it? Or does the cliffhanger get skipped?

### The Bridge Line

When a cliffhanger-to-hook transition is AND THEN, the fix is usually one of:
- **Add a bridge line to the cliffhanger:** "I know someone who can help..." (sets up the next location)
- **Modify the hook:** Open with acknowledgment of the previous state before moving to the new situation
- **Add a spatial transition:** A brief beat showing movement between locations

### Intra-Episode Transitions

The THEREFORE/BUT rule also applies WITHIN episodes, at every Kill Box section boundary:

**HOOK → SETUP → ESCALATION → TURN → CLIFFHANGER**

Each section should arise from the previous one via THEREFORE or BUT, never AND THEN. Watch especially for **convenience** — obstacles, locations, or characters that appear without setup to serve the plot. A drainage tunnel that shows up because the writer needs water, a character who arrives just in time — these feel like cheats even if the audience can't articulate why.

**Intra-episode severity:**
- **P1**: Section transition breaks the episode's internal logic. Audience doesn't understand why we're in this new beat.
- **P2**: Convenient plot device — obstacle, location, or character appears without setup.
- **P3**: Works but lazy. A stronger causal connector would improve flow.

### Validation

The Script Doctor (Pass 1: Structural) checks all transitions automatically in a single pass:
- **Inter-episode:** T-prefixed IDs (T001, T002...) for cliffhanger→hook boundaries
- **Intra-episode:** I-prefixed IDs (I001, I002...) for Kill Box section boundaries

Both sort first in the diagnostic brief, ensuring structural fixes are applied before series-level refinements.

---

## EPISODE ARC FORMAT

When specifying cliffhangers in episode_arc.md, use:

```markdown
| Ep | One-Line | Cliffhanger | Type | Intensity |
|----|----------|-------------|------|-----------|
| 1 | Description | "Cliffhanger text" | **M-CF** | 9 |
| 2 | Description | "Cliffhanger text" | **A-RE** | 8 |
```

---

## EPISODE FILE FORMAT

In generated episode files:

```markdown
# [00:70 - 00:90] THE CLIFFHANGER

Action or dialogue that ends the episode—

---

**CLIFFHANGER TYPE:** Mid-Action (M-PT) - Physical Threat
**HOOK TYPE:** Silent (S-CO) - Continuation
**NEXT:** Brief setup for next episode
```

---

## VALIDATION INTEGRATION

The validation scripts should:
1. Extract main category (M or A) from the type code
2. Check 80/20 distribution across series
3. Flag 4+ consecutive same main category (max 3 allowed)
4. Track subtype variety for reports

---

*This appendix is the canonical reference. All documents must align with this taxonomy.*
*Last updated: 2026-02-13*