# Recoil Production System
## Instruction Manual & Worksheet

---

## Overview

This system supports the full lifecycle of vertical microdrama creation:

```
DEVELOPMENT → VALIDATION → PROMOTION → TREATMENT → GENERATION → ASSESSMENT → COMPILATION → BREAKDOWN → VISUAL DESIGN → STORYBOARD
```

| Phase | Purpose | Output |
|-------|---------|--------|
| **Development** | Brainstorm, iterate, build characters | 34-point checklist + dev docs |
| **Validation** | Verify dramatic infrastructure | Pass/fail gates |
| **Promotion** | Convert to scripting format | Bible + state files |
| **Treatment** | Transform outline to prose paragraphs | treatment.md (MASTER document) |
| **Generation** | V12 engine produces 60 episodes | Scripts in /episodes/ |
| **Assessment** | Find quality issues | Prioritized fix list |
| **Compilation** | Merge into single file | Fountain screenplay |
| **Breakdown** | Extract visual assets from scripts | visual/breakdown.json |
| **Visual Design** | Create visual bible (lens, palettes, refs) | visual_bible.md |
| **Storyboard** | Generate shot-by-shot production JSON | storyboards/*.json |

---

## Folder Structure

```
/recoil/
├──                     ← Shared library (you are here)
│   ├── skills/                 ← Stable reference (READ-ONLY, 7 engine skills)
│   │   ├── format_v12/SKILL.md
│   │   ├── dramatic_elements/SKILL.md
│   │   ├── treatment/SKILL.md  ← Prose format, THE MOMENT, cliffhanger images
│   │   ├── relationship_earning/SKILL.md
│   │   ├── orchestration_process/SKILL.md
│   │   └── calibration/SKILL.md
│   ├── agents/                 ← Agent protocols (21 total)
│   │   ├── develop_agent.md
│   │   ├── showrunner_agent.md
│   │   ├── treatment_agent.md
│   │   ├── dramatic_qc_agent.md
│   │   └── ...
│   ├── lenses/                 ← Dramatic QC lenses (7 total)
│   │   ├── behavioral_dna.md
│   │   ├── voice.md
│   │   ├── texture.md
│   │   └── relationship_earning.md
│   ├── editors/                ← Visual editors + Pre-Production Console
│   │   ├── prepro-console.html     ← Tabbed app (Screenplay/Grammar/Visual Bible/Casting/Breakdown/Storyboard)
│   │   ├── shootout_reviewer.html  ← A/B model comparison tool
│   │   ├── voice_casting.html      ← Voice casting + TTS preview
│   │   ├── modules/               ← Console tab modules (app.js, api.js, score.js, etc.)
│   │   ├── styles/                ← Shared CSS
│   │   ├── serve.py               ← Local dev server (127.0.0.1:8420)
│   │   ├── _standalone/           ← Backward-compatible standalone HTML editors
│   │   └── _archive/             ← Archived editors (index.html, revision.old.html)
│   ├── tools/                  ← Automation scripts (72 Python tools)
│   │   ├── validate_treatment.py
│   │   ├── compile_treatment.py
│   │   ├── compile_episodes.py
│   │   └── ...
│   ├── templates/
│   ├── calibration/
│   ├── evaluation/              ← Validation gate specifications
│   │   └── arc_validation_gate.md
│   └── SCRIPTING_REQUIREMENTS.md ← 34-point checklist (character-first)
│
└── _docs/                      ← Documentation
    └── PRODUCTION_PIPELINE_GUIDE.md ← Complete workflow reference

/projects/                           ← ALL SHOWS (sibling to /recoil/)
├── leviathan/
│   ├── development/                 ← Brainstorming playground
│   ├── treatment.md                 ← MASTER document for generation
│   ├── bible/
│   ├── episodes/
│   └── state/
├── tartarus/
├── olympus/
└── _archive/
```

---

# WORKFLOWS

## Workflow A: Start from Scratch

**When to use:** You have a vague idea or just a genre preference.

### Step 1: Brainstorm
Open Claude Code and say:
```
Brainstorm 5 microdrama premises for me.

Genre preference: [e.g., "sci-fi noir"]
Tone preference: [e.g., "dark and gritty"]
```

Claude generates 5 complete premise packages with logline, genre blend, lens, emotional anchor, and demographic hook.

### Step 2: Pick One
Say:
```
Let's develop [Title].
```

Claude creates `/projects/[title]/development/` with STATUS.md initialized.

### Step 3: Work the Checklist
Work through STATUS.md items. After each session, Claude updates progress. Documents (characters.md, thematic_spine.md, etc.) get created as decisions solidify.

### Step 4: Promote
When STATUS.md shows 34/34:
```
Promote [title] to scripting.
```

---

## Workflow B: Start with Existing Materials

**When to use:** You have a screenplay, outline, treatment, or notes already.

### Step 1: Create Dev Folder
Say:
```
Create a development folder for a project called [Name].
```

Claude creates `/projects/[name]/development/` with STATUS.md.

### Step 2: Upload Your Materials
Drop your existing files into the dev folder:
- Screenplay drafts
- Character notes
- World-building docs
- Structure outlines
- Reference images
- Anything relevant

No naming convention required — use whatever filenames you have.

### Step 3: Let Claude Audit
Say:
```
I've uploaded existing materials to /projects/[name]/development/.
Read everything and update STATUS.md based on what's already defined.
```

Claude reads your docs, checks off completed items, and tells you what's missing.

### Step 4: Fill Gaps
Work through remaining checklist items. Claude can generate missing pieces from your existing materials.

### Step 5: Promote
When 34/34:
```
Promote [name] to scripting.
```

---

## Workflow C: Resume a Development Session

**When to use:** Returning to an in-progress idea.

Say:
```
Let's continue working on [project name].
Read /projects/[name]/development/STATUS.md and show me current progress.
```

Claude reads the status, shows what's done vs. pending, and picks up where you left off.

---

## Workflow D: Run Episode Generation

**When to use:** Project is in scripting, ready to generate episodes.

**IMPORTANT:** Always start with `/load-context [project] generate` to load required context.

### Option 1: Fresh Start
```
/load-context [project] generate
/generate-script-orchestrated [project]
```

### Option 2: Resume from Checkpoint
```
/load-context [project] generate
/generate-script-orchestrated [project] --from [batch]
```

Claude reads the state file and continues from the specified batch.

---

# REFERENCE

## The 34-Point Checklist (Character-First Sequencing)

These are the requirements for promotion to scripting (from SCRIPTING_REQUIREMENTS.md):

**CRITICAL:** Characters come BEFORE theme articulation. Theme is DISCOVERED through character collision, not designed upfront.

### SECTION 1: Characters First (10 items)
1. [ ] Protagonist sketch (name, age, role, competence)
2. [ ] Protagonist behavioral DNA (3+ behaviors, stress, signature line, orthogonal trait, contradiction)
3. [ ] Antagonist sketch (name, role, what makes them SMART)
4. [ ] Antagonist behavioral DNA (3+ behaviors, stress, signature line, what they're RIGHT about)
5. [ ] Emotional anchor sketch (name, relationship, how they challenge protagonist)
6. [ ] Anchor behavioral DNA (3+ behaviors, danger response, truth they hold)
7. [ ] Voice patterns defined (idiom, relational shorthand, anti-patterns)
8. [ ] Voice consistency checklist (distinct patterns, no contamination, swap test)
9. [ ] Character tone & humor (type, funny lines, when humor shifts)
10. [ ] Protagonist need layers (surface, deeper, deepest)

### SECTION 2: Pressure Test (2 items)
11. [ ] Collision sequence written (3 test episodes)
12. [ ] Theme discovery (name what emerged from collision)

### SECTION 3: Thematic Spine (5 items) — NOW articulate theme
13. [ ] "This is really about..." (emerged from collision)
14. [ ] Thematic question (debatable, no easy answer)
15. [ ] Protagonist's thematic stance (revealed through collision choices)
16. [ ] Antagonist's counter-thesis (defensible opposing answer)
17. [ ] Mythological DNA (archetype/myth echo)

### SECTION 4: Concept & Hook (5 items)
18. [ ] Surprising conceit (subverts expectation)
19. [ ] Logline (protagonist + goal + stakes + setting)
20. [ ] Genre blend (primary + secondary)
21. [ ] Demographic hook (competence porn, gamification, sigma flip)
22. [ ] Archetype-Worldview (type + visual manifestation)

### SECTION 5: Emotional Architecture (4 items)
23. [ ] Anchor type (CUB/GHOST/MIRROR/SKEPTIC/TETHER/WITNESS/FOIL/COST — see CONSTANTS.md)
24. [ ] Anchor need layers
25. [ ] Primary Ache (what audience yearns for)
26. [ ] Relationship milestones mapped

### SECTION 6: World (3 items)
27. [ ] Setting (where, when, sensory details)
28. [ ] Rules/constraints (pressure cooker)
29. [ ] Factions/power structure

### SECTION 7: Structure (5 items)
30. [ ] 3-act breakdown
31. [ ] 8-sequence skeleton
32. [ ] Key plot points (Ep 15, 30, 45, 60)
33. [ ] Emotional beat schedule (11 required beats)
34. [ ] Thematic checkpoints verified

---

## Thematic Arc Development

When building the 60-episode arc, theme drives structure.

### Choose an Arc Type

| Arc Type | Description | Best For |
|----------|-------------|----------|
| **Positive** | Protagonist believes Lie, learns Truth | Classic hero's journey |
| **Flat** | Protagonist holds Truth, changes World | Competence porn, sigma flip |
| **Negative** | Protagonist descends | Tragedy, anti-hero |
| **Disillusionment** | Protagonist learns harsh truth | Noir, cynical |
| **Revelation** | Protagonist incomplete, becomes whole | Mystery, identity |

**For target demo, Flat Arcs often work best** — hero is already right, system is wrong.

### Structure by Act
- **Act I (1-15):** Protagonist's stance clashes with world's stance
- **Act II (16-45):** Stance tested, challenged, pressured; antagonist offers counter-thesis
- **Act III (46-60):** Protagonist embodies answer through action, not speech

### Every Sequence Has a Thematic Function
| Sequence | Episodes | Thematic Function |
|----------|----------|-------------------|
| 1 | 1-8 | Establish the question through protagonist's world |
| 2 | 9-15 | The question becomes personal |
| 3 | 16-23 | Protagonist's stance is tested |
| 4 | 24-30 | Midpoint — question deepens |
| 5 | 31-38 | Pressure mounts; cracks appear |
| 6 | 39-45 | All Is Lost — question becomes urgent |
| 7 | 46-53 | Resolution begins to emerge |
| 8 | 54-60 | The answer is lived, not spoken |

---

## V12 Constraints (Scripting)

When generating episodes, these rules apply:

| Constraint | Value |
|------------|-------|
| Word count | 450-500 (see `CONSTANTS.md`) |
| Dialogue cap | 40% max (per CONSTANTS.md) |
| Dialogue exchanges | Up to 8 per episode max (per CONSTANTS.md) |
| Hook | 80% silent / 20% dialogue (validation: 70-85% range, per CONSTANTS.md) |
| Cliffhanger ratio | 80% mid-action / 20% aftermath (validation: 70-85% range, per CONSTANTS.md) |
| Action paragraphs | 1-3 lines (4 max), shot-aware |

> **Single source of truth:** All numeric values are defined in `/CONSTANTS.md`.

---

## Character Expression Variety

Character elements should feel organic, not mechanical:

| Element | Frequency | Anti-Pattern |
|---------|-----------|--------------|
| Behavioral DNA | 2-3 per batch | Same behavior 2+ consecutive eps |
| Idiom/Voice | 3-4 per batch | Forcing idiom every episode |
| Signature line | 2-3 per act | Overusing signature phrases |
| Stress behavior | Key moments only | Every conflict triggers it |

**The Rule:** If you notice you're checking a box, you're doing it wrong.

---

## Deviation Handling

When generation produces episodes outside constraints, the system auto-regenerates:

| Issue | Action |
|-------|--------|
| Word count over | Regenerate with trim focus (max 2x, then flag) |
| Word count under | Regenerate until ≥450 (no limit) |
| Dialogue excess | Regenerate with dialogue cap |
| Pattern violation | Regenerate with forced interrupt |
| Voice drift | Reload characters.md, regenerate |

All deviations are logged. Flagged issues are addressed during `/rewrite`.

**Full specification:** `/DEVIATION_RULES.md`

---

## Goal-Backward Verification

At milestone batches, verify arc trajectory:

| Batch | Episode | Threads | Beats |
|-------|---------|---------|-------|
| 3 | 15 | 0-1 | 2/11 |
| 6 | 30 | 2-3 | 5/11 |
| 9 | 45 | 4-5 | 8/11 |
| 12 | 60 | 6+ | 11/11 |

If off-track, generate course corrections before continuing.

---

## Key Prompts (Copy-Paste Ready)

### Brainstorm New Ideas
```
Brainstorm 5 microdrama premises for me.

Genre preference: [optional]
Tone preference: [optional]
Setting preference: [optional]
```

### Start New Development Project
```
Create a development folder for a project called [Name].
Initialize STATUS.md and help me work through the checklist.
```

### Import Existing Materials
```
I've uploaded existing materials to /projects/[name]/development/.
Read everything and update STATUS.md based on what's already defined.
```

### Check Progress
```
Read /projects/[name]/development/STATUS.md and show me current progress.
What's still needed for scripting readiness?
```

### Promote to Scripting
```
Promote [name] to scripting.
```

### Generate Episodes
```
Generate all 60 episodes using the orchestration prompt.
Read / for format rules and /bible/ for series details.
```

### Resume Generation
```
Resume [project] generation from the last checkpoint.
```

### Compile Episodes to Single File
```
Compile [project] episodes into a single fountain file.
```
Or run the script directly:
```bash
python /tools/compile_episodes.py /path/to/project
```

---

## Workflow E: Compile Episodes Post-Generation

**When to use:** After generating all 60 episodes, compile them into a single .fountain screenplay file.

### Option 1: Ask Claude
```
Compile the episodes in /olympus/ into a single fountain file.
```

### Option 2: Run the Script Directly
```bash
cd /recoil
python tools/compile_episodes.py ./olympus
```

This will:
1. Read all `ep_XXX.md` files from `/olympus/episodes/`
2. Strip metadata (word counts, loglines, cliffhanger annotations)
3. Combine into `OLYMPUS_COMPLETE.fountain` in the project root
4. Add title page and page breaks between episodes

**Custom output name:**
```bash
python tools/compile_episodes.py ./olympus FINAL_DRAFT.fountain
```

---

## Dramatic Quality Control System

The system includes dramatic quality validation (not just structural compliance):

### Validation Gates

| Gate | Type | When |
|------|------|------|
| **Behavioral DNA Gate** | Hard | Pre-promotion |
| **Arc Validation Gate** | Hard | Pre-promotion |
| **Mechanical QC** | Hard | Each batch |
| **Quality Gate** | Hard | Each batch |
| **Dramatic QC Gate** | Soft | Each batch |

### Commands

```
/dramatic-qc [project] --mode pre              # Pre-generation validation
/dramatic-qc [project] --mode post --batch 3   # After batch
/dramatic-qc [project] --mode assess --lens all # Full assessment
```

### Available Lenses

| Lens | What It Checks |
|------|----------------|
| `behavioral_dna` | Character specificity, stress behaviors, signature lines |
| `voice` | Distinctiveness, swap test, contamination |
| `texture` | Emotional register, surprise, earned declarations |
| `relationship_earning` | Demonstrated vs declared connections |
| `visual_richness` | Cinematic specificity, shot-aware prose, sensory detail |
| `continuity` | Thread tracking, callback accuracy, state consistency |
| `double_view_continuity` | Re-watch value, planted/payoff alignment, hidden layers |

See `/agents/dramatic_qc_agent.md` and `/lenses/` for details.

---

## File Locations Quick Reference

| What | Where |
|------|-------|
| V12 Format Rules | `/skills/format_v12/SKILL.md` |
| Variety Toolkit | `/appendix_b_variety.md` |
| Emotional Architecture | `/appendix_c_emotion.md` |
| Scripting Requirements | `/SCRIPTING_REQUIREMENTS.md` (34-point, character-first) |
| Episode Compiler | `/tools/compile_episodes.py` |
| Status Template | `/templates/STATUS_TEMPLATE.md` |
| Dramatic QC Agent | `/agents/dramatic_qc_agent.md` |
| Behavioral DNA Lens | `/lenses/behavioral_dna.md` |
| Development Projects | `/projects/[project-name]/development/` |
| Scripting Projects | `/projects/[project-name]/` |

---

## Typical Session Examples

### "I have a vague idea about underground racing"
```
Brainstorm 5 microdrama premises involving underground racing.
Tone preference: Fast and Furious meets cyberpunk
```

### "I wrote a pilot script, can we build from that?"
```
Create a development folder called neon-drift.
I'm uploading my pilot script. Read it and map what I have to STATUS.md.
```

### "Where did we leave off on Ares?"
```
Read /projects/ares/development/STATUS.md and summarize progress.
Let's work on the next incomplete section.
```

### "Ares is ready, let's make it real"
```
Promote Ares to production.
```

### "Generate the first batch of episodes for Ares"
```
Open /recoil/ares/ and generate Episodes 1-5 using V12 constraints.
```

---

## Tips

1. **Work in sessions.** You don't need to complete STATUS.md in one sitting. Claude picks up where you left off.

2. **Upload anything.** Messy notes, half-finished scripts, reference images — Claude will parse what's useful.

3. **The checklist is a guide, not a prison.** Some items may merge or evolve as you develop the idea.

4. **Promote when ready, not when perfect.** 34/34 means "enough to generate." You can still refine during production.

5. **Checkpoints are your friend.** Generation saves state after every 5 episodes. Context limits are not a problem.

---

## Batch Enforcement System

A global hook enforces batch discipline during episode generation. This prevents skipping checkpoints or rushing through episodes without proper state tracking.

### How It Works

- **Episodes 1-5:** Always allowed (first batch)
- **Episodes 6+:** BLOCKED unless previous batch checkpoint exists

### Location

```
/recoil/.claude/
├── settings.json                  ← Hook configuration
└── hooks/
    ├── episode_enforcement.py     ← Blocks writes without checkpoints
    └── save_checkpoint.py         ← Helper to save batch checkpoints
```

### After Each Batch of 5 Episodes

```bash
python3 .claude/hooks/save_checkpoint.py ./[project-name] [batch_number]

# Examples:
python3 .claude/hooks/save_checkpoint.py ./leviathan 1    # After eps 1-5
python3 .claude/hooks/save_checkpoint.py ./leviathan 2    # After eps 6-10
```

### What Happens If You Try to Skip

If you try to write episode 6 without a batch 1 checkpoint:
```json
{
  "decision": "block",
  "reason": "ENFORCEMENT [leviathan]: Cannot write episode 6 (batch 2). Missing checkpoint for batch 1."
}
```

### Notes

- Enforcement only applies to scripting projects (those with a `state/` folder)
- Development projects in `/projects/[project]/development/` are not affected
- The hook works for ALL scripting projects automatically

---

## Troubleshooting

**"Claude isn't reading my uploaded files"**
→ Make sure files are in the correct `/projects/[project]/development/` folder. Say explicitly: "Read all files in this folder."

**"STATUS.md doesn't reflect my materials"**
→ Say: "Re-read my uploaded materials and update STATUS.md. Be thorough."

**"Promotion to scripting failed — missing items"**
→ Claude will list what's missing. Address those items, then try again.

**"Generation stopped mid-batch"**
→ Normal with long contexts. Say: "Resume from the last checkpoint." Claude reads state and continues.

**"Voice is drifting in later episodes"**
→ Say: "Re-read characters.md and correct the voice drift in the next batch."

---

*System version: V12 | Last updated: January 2026*