Driving Variants From a Google Sheet¶

For Lvl 1 and Lvl 2 variants, editing a Google Sheet is usually faster than asking Claude to patch the .nbflow. The workflow connects directly to a Sheet — you change a cell, the workflow picks it up on the next run.

This is the recommended way to manage dialogue swaps and wardrobe variants once you have more than a couple of versions to track.

Why a Sheet beats per-variant `.nbflow` edits¶

For Lvl ½ variants specifically:

Approach	What it looks like
Ask Claude to patch the `.nbflow`	Claude reads the file, finds the dialogue / wardrobe nodes, edits each, saves a new versioned file, updates the registry. Per-variant.
Edit the Sheet	You open the Sheet, change one row's `dialogue` cell. Workflow re-runs against the same Sheet, picks up the change. No file patch, no version bump per dialogue tweak.

For a workflow you're going to riff on heavily — multiple dialogue variants, multiple wardrobe variants, A/B testing hook lines — the Sheet is dramatically less friction.

You still bump versions when the workflow's structure changes (a Lvl 3 environment swap, a Lvl 4 new scene). But for in-place Lvl ½ work, the Sheet is the editing surface.

How the connection works¶

A Sheet-driven workflow has its Dynamic Prompt nodes wired to read from a Google Sheet instead of (or alongside) their inline rows. The most common pattern: dialogue and wardrobe live in Sheet columns, the workflow pulls them per run.

Setup (one-time per workspace):

Connect Google account — PatchWork Settings → Google Drive → Connect (the OAuth covers Sheets too)
Grant Sheets access — read/write scope
Verify the connection — Settings shows the connected account email

Once connected, Sheets URLs and IDs can be pasted into any Sheets-aware node in PatchWork.

Sheet structure for variant work¶

A typical Sheet for Lvl ½ variant editing looks like:

scene	dialogue	wardrobe	setting	notes
01	"If you're a woman over 40..."	white linen shirt	kitchen window light	hook
02	"I'm 47 and 6 months ago..."	white linen shirt	kitchen window light	personal anchor
03	"Brain fog. Mood swings. 3am wake-ups."	white linen shirt	kitchen window light	symptom cluster
...

The columns map to template placeholders:

dialogue column → fed into the Veo template's {dialogue} placeholder
wardrobe column → fed into the image template's {wardrobe} placeholder
setting, notes, etc. → other placeholders or human-readable context

This is the same dynamic-feeds-template pattern the workflows already use — the only difference is that the dynamic's rows come from a Sheet row instead of being typed into the node directly.

Day-to-day workflow¶

flowchart TD
    A[Open the Sheet] --> B[Edit a dialogue<br/>or wardrobe cell]
    B --> C[Save - Sheets<br/>auto-saves]
    C --> D[Re-run the workflow<br/>in PatchWork]
    D --> E[Workflow pulls<br/>the updated cells]
    E --> F[Fresh candidates<br/>with the new copy]

No file patching. No .nbflow version bump per dialogue tweak. The Sheet IS the variant history.

When the Sheet is worth it¶

Situation	Sheet vs. file patch
You're going to try 5+ dialogue versions of a hook	Sheet wins, by a lot
You're A/B testing wardrobe across accounts	Sheet wins
A non-technical teammate writes dialogue	Sheet wins (they don't touch PatchWork)
Single one-off dialogue tweak you'll never revisit	File patch is fine
You want a permanent versioned record of each variant	File patch (bumps a version each time)

The trade-off: Sheet edits don't bump V0-N — they're live edits to the same workflow file. If you need a versioned snapshot of "this exact dialogue at this exact moment," that's still a .nbflow bump.

In practice, treat the Sheet as the working copy and bump the .nbflow only when you're shipping a meaningful new variant to production. See Variants & versioning for what counts as meaningful.

Beyond variants — batch generation and tracker sync¶

The same Sheets integration powers two other use cases worth knowing about:

Batch generation across many rows: A workflow parameterized by Sheet rows can produce N runs from N rows in one pass. Useful for A/B testing 20 hook variations or generating per-product variants across 30 products. The workflow generates one candidate set per row — pick the strongest of each.
Project state sync (master tracker): The tracker-sync skill uses the same Google Sheets connection to keep the master workflow tracker up to date. After a workflow ships, tracker-sync reads reference/version-registry.json and pushes per-workflow rows (current version, status, fan-out state, Drive link) to the tracker. You'll use this in Chapter 7 after fanning out.

Limitations¶

Sheets is rate-limited by Google — 60 reads/minute per user is the soft cap. Normal variant work stays well under this; only matters for batch generation.
No real-time sync — when you edit a Sheet, PatchWork doesn't auto-refresh. You re-run the workflow to pick up changes, or trigger a manual re-sync.
Schema drift — if you rename a column, every workflow pointing at that Sheet breaks. Treat column names as a contract.

When you're ready¶

→ Next: Targeted one-line fixes — for one-line fixes that don't need a full variant or a Sheet round-trip.