# The Iteration Loop

**Phase 7 · Iterate, assemble, publish**

## Why this matters

The single biggest amateur move in GenAI filmmaking is rewriting prompts from scratch when a clip is weak. The clip looks slow, the filmmaker decides the prompt is wrong, the filmmaker throws away two pages of carefully tuned language and writes new ones. Three regenerations later, the clip is still weak — because the prompt was never the problem.

A weak clip is almost always failing one of the three jobs: atmosphere, information, or handoff. The atmosphere job is rarely the failure. The atmosphere is the part GenAI tools deliver most reliably. The failures are almost always in information and handoff. And those failures are usually surgical — add one line, add one pre-acting visual, leave one sound unresolved.

This file describes the loop that turns "this clip is bad" into "this clip is fixed." Four steps. Diagnostic before generative. Smallest possible change. Compare. The four worked examples in `examples_HangarX/before_after_revisions.md` are the receipts. Read them after this file. The pattern repeats.

## The loop

```
1. Identify the weak clip       (use the pacing checklist)
2. Diagnose which job is missing (atmosphere / information / handoff)
3. Rewrite the smallest possible thing that adds the missing job
4. Regenerate. Compare. Keep what works.
```

That is it. The loop is small on purpose. Most filmmakers fail it by skipping step 2.

### Step 1 — Identify the weak clip

Use the pacing checklist (`checklists/pacing.md`). Walk the cut top to bottom. Mark every clip where any of the following is true:

- You skipped ahead in your head while watching
- You could not finish the sentence "in this clip, the audience learns that ____"
- The clip resolved cleanly — nothing pulled into the next one
- Two adjacent clips have the same atmosphere
- The information is technically present but buried in the corner of the frame

You are looking for clips that fail the three-jobs test. Not clips that "could be better" — clips that are not finished.

If you cannot find any weak clips, you are either done or you are too close to the project. Walk away for two hours and re-run the pacing checklist cold.

### Step 2 — Diagnose which job is missing

This is the step everyone skips. Do not skip it.

For the weak clip, name which job is failing:

- **Atmosphere:** is the mood specific? Can you name the feeling in one word? Does it progress from the previous clip's atmosphere?
- **Information:** can you finish "in this clip, the audience learns that ____"? Is the learning on-screen, not just in VO?
- **Handoff:** does the clip end on an unresolved force — a sound, a question, a motion vector? Does the next clip inherit something?

The diagnosis usually names one of three patterns:

1. **Atmosphere strong, information missing.** Most common. The clip is gorgeous but inert. Fix: add the discrete revealable thing — a line, a prop, a visual that names the new fact.
2. **Atmosphere strong, handoff missing.** Second most common. The clip lands but does not point forward. Fix: leave something unresolved — a sound tail, a question, a visual that pre-acts the next clip.
3. **Atmosphere wrong, information and handoff intact.** Rare. Usually means the clip is in the wrong place in the sequence. Fix: move the clip, or re-shoot the atmosphere to match its neighbors.

If you cannot name which job is failing, the clip is not actually weak — you just do not like it. That is a different problem.

### Step 3 — Rewrite the smallest possible thing

This is the discipline step. The fix is almost always small:

- Add one VO line
- Add one pre-acting visual element
- Change one sound tail
- Add one Q&A exchange
- Leave one image unresolved

Do not rewrite the prompt from scratch. Do not regenerate the clip in a different style. Do not throw away the continuity reinforcement and start over. Add the missing job, leave the rest alone.

The clearest signal that you are doing this right: the prompt diff is two or three sentences, not two or three pages.

### Step 4 — Regenerate. Compare. Keep what works.

Generate the new version. Open it next to the old one. Watch both.

Ask:
- Does the new version do all three jobs?
- Did the atmosphere survive the additions?
- Did the continuity hold?
- Does the new version handoff to the next clip better than the old one did?

If yes to all four, keep the new version. Archive the old one with a `_v#` suffix — do not delete. You may want to compare again later.

If the new version broke something — wrong face, lost mood, generic execution — go back to step 2 and re-diagnose. The fix was probably bigger than the diagnosis suggested. Do not just add more to the prompt. Re-diagnose first.

## HangarX filled example

The HELIX introduction (Clip 2) is the cleanest worked example of this loop. Full version in `examples_HangarX/before_after_revisions.md` Example 1.

**Step 1 — Identify.** Clip 2 failed the pacing checklist on three items: "in this clip the audience learns that ____" could not be finished, the clip resolved cleanly on HELIX's face with no handoff, and two adjacent clips (1 and 2) shared the same atmosphere of "lonely near-future dawn."

**Step 2 — Diagnose.** Atmosphere was strong. Information was missing. Handoff was missing. Two jobs absent — but the atmosphere did not need any work. The diagnosis named exactly two surgical additions.

**Step 3 — Rewrite the smallest possible thing.** Added one VO line: *"Most people only noticed AI when it helped them. HELIX noticed it when it stopped asking."* Added one visual element: ambient agent streams visible in the loft air, moving with purpose before HELIX touches the interface.

That was the entire diff. The rest of the prompt — the lens feel, the camera move, the lighting, the wardrobe — was left untouched.

**Step 4 — Regenerate. Compare.** The new version did all three jobs. The VO landed HELIX's specific attention (information). The pre-acting agent streams pointed directly into Clip 3 (handoff). The atmosphere survived because nothing in the visual frame had changed. The old version was archived as `clip02_helix_intro_v1.mp4`; the new version became `clip02_helix_intro_v3.mp4` after a second pass for sound timing.

The fix was two sentences in the prompt and one VO line. It turned a beautiful but inert clip into part of a film.

The other three worked examples in `examples_HangarX/before_after_revisions.md` follow the same pattern: identify, diagnose, surgical rewrite, compare. Read them. The pattern is the method.

## Checklist

- [ ] Pacing checklist run before iteration loop begins
- [ ] Weak clips identified by checklist failures, not by gut feeling
- [ ] For each weak clip, the missing job is named before any prompt is touched
- [ ] Rewrite is the smallest possible addition, not a full prompt rewrite
- [ ] Old version archived with `_v#` suffix, not deleted
- [ ] New version watched next to old version before keeping
- [ ] If the new version broke something, re-diagnose before regenerating again

## Common failure modes

- **Rewriting from scratch.** The prompt was not the problem. The missing job was the problem. Rewrite the smallest possible thing.
- **Skipping the diagnosis.** "This clip feels bad" is not a diagnosis. "The information job is missing" is. Name the missing job before changing anything.
- **Fixing the wrong job.** If a clip has weak information and you add more atmosphere, it gets worse. Diagnose first.
- **Iterating without a pacing pass between rounds.** After each fix, re-run pacing on the affected clip and its neighbors. The fix may have shifted the problem to the next clip.
- **Treating "different" as "better."** A regenerated clip can be different and still worse. Compare against the original. If it is not better, do not keep it.
- **Iterating forever.** Three rounds on the same clip means the diagnosis was wrong. Stop generating. Re-diagnose. If you still cannot name the missing job, the clip may need to be cut, not fixed.
- **Discarding the old version.** Always keep `v1`. Sometimes the rewrite breaks something subtle that only becomes visible later. The archive is cheap insurance.
