Skip to content

Graduation: When to Bump to V{N+1}

The end of the testing phase. The variant has been through enough iterations that it's ready — it goes from V{N+1}-0-N in testing/ to V{N+1} in approved/.

This step requires explicit user approval. The pipeline never auto-graduates.

The bar

The variant graduates when all of these are true:

  • Every scene has acceptable candidates — at least 3 of 4 candidates per scene are usable
  • No outstanding AI tells the user is willing to accept
  • Compliance is clean — no banned words, no off-brand angles
  • The user explicitly approves — typed or said affirmatively that this variant is ready

That last one is the one you can't skip. The Manager will not graduate the variant on its own.

What graduation actually does

Mechanically, graduation is a rename + move:

testing/XYZS1-V2-0-4.nbflow  →  approved/XYZS1-V2.nbflow

The file content stays the same; the path and the version string change. The version registry's current_version updates to V2. The history list gets a final entry: "V2-0-4 → V2 graduated on YYYY-MM-DD, all scenes clean, user approved".

After graduation

The graduated V2 is now your approved baseline. From here:

  • Lvl 1-2 variants of V2 (dialogue swaps, wardrobe changes) decimal-bump: V2 → V2-1 → V2-2
  • Lvl 3-4 variants of V2 enter testing toward V3: V2 → V3-0-1 → V3-0-2 → V3
  • Fan-out to remaining accounts happens within V2 (one workflow, multi-tab) or via a decimal bump if the fan-out introduces meaningful per-account changes

Common graduation timing mistakes

Graduating too early
You're tired of testing and want to ship. Resist this. A premature graduation means the workflow is in approved/ but produces bad outputs — the team will run it expecting it to work, hit issues, and lose trust in the version registry. The cost of one more testing iteration is much lower than the cost of a bad approved workflow.
Never graduating
You're at V2-0-12 and the workflow is genuinely fine; you're just nitpicking. If 3 of 4 candidates per scene are clean and there are no AI tells, ship it. Perfect is the enemy of done.
Graduating without fan-out testing
The variant works on the test account but you haven't fanned out yet. Don't graduate. The fan-out itself is part of the testing journey. Stay in V2-0-N until fan-out is clean across all target accounts, then graduate.

When to graduate WITHOUT fan-out

A subtle case: sometimes the variant is for one specific account only — not meant to be fanned out. Example: an experimental Lvl 4 with a new prehook just for Account A.

In that case:

  • Graduate the variant as V2-account-A.nbflow (filename indicates scope) OR
  • Graduate as V2 but document in the registry that fan-out is intentionally skipped

Use judgment. The default expectation is fan-out happens; document exceptions explicitly.

The graduation conversation

A typical graduation looks like this:

You: how's XYZS1-V2-0-4 looking? Ready to graduate?

Claude:
  Status of XYZS1-V2-0-4:
    Scenes: 8 of 8 have clean candidates (4 of 4 in all but Scene 03,
            which has 3 of 4)
    AI tells: none currently flagged
    Compliance: clean — no banned words, all angles approved
    Fan-out: tested on Account A only so far

  Two options:
  1. Graduate now to V2 (Account A only, fan-out follows separately)
  2. Fan out to remaining accounts inside V2-0-N first, then graduate

  Which would you like?

You: option 2 — fan it out and graduate the combined version

Claude:
  Following Fan-out Protocol on V2-0-4. Will bump to V2-0-5 with all
  account tabs after fan-out, then we can decide on graduation.

The Manager doesn't decide for you. It surfaces the choice.

After graduation — what's locked in

Once a variant is V2 in approved/:

  • The .nbflow file is the canonical version. Future variants reference it as their starting point
  • The R2 URLs in it are stable — they don't expire
  • The version registry shows V2 as current — every tooling check uses this as the source of truth
  • Backups remain in backups/ for all the -0-N iterations that came before — audit trail preserved

You can still make Lvl 1-2 variants (V2-1, V2-2) and Lvl 3-4 variants (V3-0-1, ...) of V2. Graduation isn't an end state; it's a checkpoint.

When you're ready

You've finished Chapter 5. You now know:

  • How Lvl 3 and Lvl 4 variants differ from Lvl 1-2
  • How to plan a Lvl 4 structural change with an explicit diff
  • The testing phase rhythm (-0-N iteration, bump per change)
  • When to reach for prompt-tuning during testing
  • The graduation bar and approval mechanics

→ Next: Chapter 6 — Fan-out & Multi-account. Once a workflow is at V1+ (or a variant has graduated), ship it to the remaining target accounts. The 7-step protocol.