{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-variation-workflows-reference",
  "slug": "variation-workflows-reference",
  "title": "Controlled variation workflows: practical reference",
  "summary": "Controlled software-variation workflow covering setup-only agent prompts, single-variable matrices, baseline repository capture, isolation and fan-out, identical verification, diff and UI review, five decision outcomes, convergence, troubleshooting, and…",
  "category": "Planning",
  "tags": [
    "variations",
    "verification",
    "comparison"
  ],
  "sources": [
    {
      "label": "Portable Codex workflow resources",
      "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
    }
  ],
  "sourceUnits": [
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Agent Setup Prompt",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Big Idea",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Try This Now",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/When To Reach For This",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/How This Used To Work",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Core Pattern",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/One Dimension Rule",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Variation Matrix",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Variation Matrix/Example: Billing Webhook Duplicate Processing",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Start From The Section 5 Seed",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Save Repo State Before Fan-Out",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Choose Isolation",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Build Candidate Prompts",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Fan-Out",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Verify Every Candidate",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Review Surface",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Decision Outcomes",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Ask The Agent This",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/What To Confirm / How To Know It Worked",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/If It Goes Wrong",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/If It Goes Wrong/Candidates Changed Multiple Variables",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/If It Goes Wrong/Verification Differs Per Candidate",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/If It Goes Wrong/Repo Was Dirty Before Fan-Out",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/If It Goes Wrong/Best Idea Is Split Across Candidates",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/If It Goes Wrong/All Candidates Fail",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/References And Resources",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "planning",
  "wordCount": 3881,
  "url": "/topics/codex-variation-workflows-reference/",
  "markdownUrl": "/markdown/codex-variation-workflows-reference.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-variation-workflows-reference.json",
  "headings": [
    {
      "id": "agent-setup-prompt",
      "text": "Agent Setup Prompt",
      "level": 2
    },
    {
      "id": "big-idea",
      "text": "Big Idea",
      "level": 2
    },
    {
      "id": "try-this-now",
      "text": "Try This Now",
      "level": 2
    },
    {
      "id": "when-to-reach-for-this",
      "text": "When To Reach For This",
      "level": 2
    },
    {
      "id": "how-this-used-to-work",
      "text": "How This Used To Work",
      "level": 2
    },
    {
      "id": "core-pattern",
      "text": "Core Pattern",
      "level": 2
    },
    {
      "id": "one-dimension-rule",
      "text": "One Dimension Rule",
      "level": 2
    },
    {
      "id": "variation-matrix",
      "text": "Variation Matrix",
      "level": 2
    },
    {
      "id": "example-billing-webhook-duplicate-processing",
      "text": "Example: Billing Webhook Duplicate Processing",
      "level": 3
    },
    {
      "id": "start-from-the-section-5-seed",
      "text": "Start From The Section 5 Seed",
      "level": 2
    },
    {
      "id": "save-repo-state-before-fan-out",
      "text": "Save Repo State Before Fan-Out",
      "level": 2
    },
    {
      "id": "choose-isolation",
      "text": "Choose Isolation",
      "level": 2
    },
    {
      "id": "build-candidate-prompts",
      "text": "Build Candidate Prompts",
      "level": 2
    },
    {
      "id": "fan-out",
      "text": "Fan-Out",
      "level": 2
    },
    {
      "id": "verify-every-candidate",
      "text": "Verify Every Candidate",
      "level": 2
    },
    {
      "id": "review-surface",
      "text": "Review Surface",
      "level": 2
    },
    {
      "id": "decision-outcomes",
      "text": "Decision Outcomes",
      "level": 2
    },
    {
      "id": "ask-the-agent-this",
      "text": "Ask The Agent This",
      "level": 2
    },
    {
      "id": "what-to-confirm-how-to-know-it-worked",
      "text": "What To Confirm / How To Know It Worked",
      "level": 2
    },
    {
      "id": "if-it-goes-wrong",
      "text": "If It Goes Wrong",
      "level": 2
    },
    {
      "id": "candidates-changed-multiple-variables",
      "text": "Candidates Changed Multiple Variables",
      "level": 3
    },
    {
      "id": "verification-differs-per-candidate",
      "text": "Verification Differs Per Candidate",
      "level": 3
    },
    {
      "id": "repo-was-dirty-before-fan-out",
      "text": "Repo Was Dirty Before Fan-Out",
      "level": 3
    },
    {
      "id": "best-idea-is-split-across-candidates",
      "text": "Best Idea Is Split Across Candidates",
      "level": 3
    },
    {
      "id": "all-candidates-fail",
      "text": "All Candidates Fail",
      "level": 3
    },
    {
      "id": "references-and-resources",
      "text": "References And Resources",
      "level": 2
    },
    {
      "id": "operational-boundaries",
      "text": "Operational boundaries",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Controlled variation workflows: practical reference\n\n## Agent Setup Prompt\n\n```text\nSet up a controlled variation run before any candidate implementation starts. Build the files, folders, isolation lanes, verification ledger, review surfaces, and saved-decision template first, then stop and report whether setup is ready.\n\n1. Work from the repository root. Choose a short run id that names the software decision, such as `billing-webhook-$(date +%Y%m%d-%H%M%S)`, and set `ROOT=\"artifacts/variations/$RUN_ID\"`.\n\n2. Create the run structure: `prompts/`, `launch/`, `logs/`, `review/`, `decisions/`, and `candidates/v1`, `candidates/v2`, `candidates/v3` under `$ROOT`. If the variation is visual, also create `review/screenshots/`.\n\n3. Write `$ROOT/matrix.md` before launching anything. Include Goal, Invariants, Variable Under Test, Candidate Count, Candidates, and Review Criteria. The matrix must name exactly one variable. Keep repo state, base prompt, target feature or bug, constraints, verification command, and review criteria identical for every candidate. If a second dimension matters, record it as a future round.\n\n4. Save the shared base prompt to `$ROOT/prompts/base.prompt.md`. Save matching launch metadata to `$ROOT/launch/base.launch.json` using Prompt Builder when available, for example `p --print-prompt \"$PROMPT\"` and `p --print-launch-json \"$PROMPT\"`. If Prompt Builder is unavailable, still write the base prompt file and create a small valid launch JSON file that records the prompt text, run id, candidate ids, artifact root, isolation method, and verification command.\n\n5. Capture baseline repo state before fan-out: save `git status --short` to `$ROOT/review/git-status-before.txt`, `git diff` to `$ROOT/review/dirty-before.patch`, and `git diff --staged` to `$ROOT/review/staged-before.patch`. If the repo has unknown dirty state, stop and report it instead of creating candidate code lanes.\n\n6. Choose the isolation strategy and record it. For prompt, plan, or docs-only variations, use `$ROOT/candidates/v1`, `v2`, and `v3`. For parallel code edits, prefer git worktrees at `../variation-$RUN_ID/v1`, `v2`, and `v3`, each on its own branch, then save `git worktree list` to `$ROOT/review/worktrees.txt`. Each candidate must have a distinct branch, worktree, or directory.\n\n7. Create `$ROOT/prompts/v1.prompt.md`, `$ROOT/prompts/v2.prompt.md`, and `$ROOT/prompts/v3.prompt.md` from the same base prompt. Append only the candidate override: candidate id, variable name, that candidate's setting, and the instruction to change no other dimension.\n\n8. Define one verification command and save it in the matrix plus `$ROOT/review/verification-command.txt`. Create `$ROOT/review/verification.tsv` with columns for candidate id, status, and command. Do not run implementation verification yet. The command must be identical for every candidate; if a candidate needs different proof, make that a new variation round.\n\n9. Create review artifacts before generation: `$ROOT/review/comparison.md` with Goal, Variable Under Test, Verification, Diff Review, Review Criteria, and Notes sections; placeholder paths for `logs/v1.verify.log`, `logs/v2.verify.log`, `logs/v3.verify.log`; placeholder paths for `review/v1.diffstat.txt`, `review/v1.diff.patch`, and matching v2/v3 files. Leave results blank until candidates exist.\n\n10. Create `$ROOT/decisions/selection.md` with fields for outcome, primary candidate, secondary candidate ids, decision, why, rejected candidates, required follow-up, final verification command, per-candidate notes, and a continue prompt. The outcome must later be exactly one of Pick, Combine, Refine, Expand, or Reject.\n\n11. Run setup checks only: confirm the matrix, base prompt, launch JSON, candidate prompts, repo-state files, verification command file, comparison template, decision template, and isolation lanes exist. Print OK or FAIL for each check and show the run file list with `find \"$ROOT\" -maxdepth 3 -type f | sort`.\n\n12. Respect privacy boundaries. Do not copy secrets, tokens, cookies, private endpoints, full environment dumps, raw private config, or unrelated home-directory files into prompts, logs, launch JSON, matrix files, review artifacts, or decisions. Summarize sensitive configuration instead of pasting it.\n\n13. Report back with the artifact root, candidate ids, chosen isolation strategy, single variable under test, single verification command, repo-state classification, setup check results, any files you intentionally did not copy for privacy, and any blocker. Do not generate candidate implementations, run candidate verification, fill comparison results, or make a Pick/Combine/Refine/Expand/Reject decision until setup verification passes and the next step is explicitly requested.\n```\n\n## Big Idea\n\nPhase: Generation And Evidence - use the prepared surface to generate comparable options and preserve the proof that decides between them.\n\n`Code is free` does not mean quality is free.\n\n## Try This Now\n\nFinish this sentence before generating candidates:\n`We are comparing candidates that differ only by __________.`\nFor a billing webhook bug, try: `idempotency strategy`.\nWrite the same verification command before any fan-out.\n\nIt means another candidate is cheap enough that the workflow should change:\n\n```text\ndo not bet everything on the first generated answer\n```\n\nProduce candidates, verify them, compare them, converge deliberately, and save the decision.\n\nCheap:\n\n- another implementation option\n- another UI integration strategy\n- another idempotency strategy\n- another test boundary\n- another prompt framing\n- another documentation organization\n\nStill expensive:\n\n- understanding the problem\n- keeping candidates controlled\n- integrating the winner\n- running verification\n- resolving conflicts\n- preserving why the decision was made\n\nPractical rule:\n\n```text\nGenerate more because comparison improves the decision, not because you are avoiding the decision.\n```\n\n## When To Reach For This\n\nUse variations when several plausible approaches exist and comparison will make the final choice better.\n\n| Use Variations For | Example |\n| --- | --- |\n| UI integration strategy | saved payment methods in checkout: inline selector vs drawer vs review-step picker |\n| idempotency strategy | billing webhook duplicate-processing: provider event guard vs invoice lock vs processing ledger |\n| auth/session architecture | middleware-first vs session-store-first vs token-rotation boundary |\n| state management | local reducer vs server state cache vs URL-backed state |\n| test boundary | unit regression vs integration replay vs end-to-end checkout path |\n| API shape | command endpoint vs resource endpoint vs explicit workflow endpoint |\n| data loading model | route loader vs component query vs server action |\n| implementation alternatives | minimal patch vs extracted helper vs explicit state machine |\n| prompt framing | plan-first vs patch-first vs test-first |\n| documentation organization | quickstart-first vs concept-first vs task checklist |\n\nSkip variations when another candidate adds noise.\n\n| Skip Variations For | Better Move |\n| --- | --- |\n| one-line typo fix | patch it and test it |\n| obvious hotfix | apply the smallest safe change |\n| strict migration | follow the migration plan exactly |\n| exact requested implementation | build what was specified |\n| unverifiable candidates | define verification first |\n| dirty repo with no saved state | checkpoint before fan-out |\n| failing test names the exact bug | fix the bug first |\n| candidates would share unsafe state | isolate before launching |\n\nHard rule:\n\n```text\nVariation is a decision tool, not a procrastination tool.\n```\n\n## How This Used To Work\n\nWhat you used to expect:\n\n```text\nAsk for one implementation, inspect it, tweak it, and hope the first path was good enough.\n```\n\nWhat the workflow gives you now:\n\n```text\nStart from one deliberate prompt, generate controlled candidates, verify each\nthe same way, compare results, then save the chosen path.\n```\n\nWhat you used to expect:\n\n```text\nMore candidates automatically means better work.\n```\n\nWhat the workflow gives you now:\n\n```text\nUnverified candidates are just noise. The value comes from controlled\ndifferences, identical verification, and a saved decision.\n```\n\n## Core Pattern\n\n```text\ngoal\n-> variable\n-> matrix\n-> isolation\n-> fan-out\n-> verify\n-> review\n-> selection\n-> convergence\n-> saved decision\n```\n\nDo not skip the middle:\n\n```text\nfan-out without isolation = collisions\nfan-out without verification = noise\nfan-out without review = drift\nfan-out without saved decision = repeated debate\n```\n\n## One Dimension Rule\n\nVary exactly one dimension across candidates.\n\nFinish this sentence before launching anything:\n\n```text\nWe are comparing candidates that differ only by __________.\n```\n\nGood variables:\n\n| Variable | Good Comparison Question |\n| --- | --- |\n| UI integration strategy | Where should saved payment methods enter checkout? |\n| idempotency strategy | Which duplicate-processing guard is safest for billing webhooks? |\n| state management | Which state boundary keeps the checkout flow simplest? |\n| test boundary | Which test layer catches this regression with the least brittleness? |\n| API shape | Which endpoint shape keeps auth/session changes clear? |\n| data loading model | Where should this screen load account and payment data? |\n| prompt framing | Which prompt produces the most verifiable implementation plan? |\n| documentation organization | Which doc structure helps the next maintainer act fastest? |\n\nBad variables:\n\n| Bad Variable | Why It Fails |\n| --- | --- |\n| random ideas | no controlled comparison |\n| each one different | impossible to know what mattered |\n| explore everything | no review question |\n| make five better versions | vague and untestable |\n| let every agent decide | candidates drift apart |\n\nIf two dimensions matter, run two rounds.\n\n```text\nRound 1: compare idempotency strategy.\nRound 2: compare test boundary for the selected strategy.\n```\n\n## Variation Matrix\n\nWrite the matrix before launching candidates.\n\n```markdown\n# Variation Matrix\n\n## Goal\n\n<What software outcome are we trying to achieve?>\n\n## Invariants\n\nThese stay the same for every candidate:\n\n- same repo state:\n- same base prompt:\n- same target feature or bug:\n- same constraints:\n- same verification command:\n- same review criteria:\n\n## Variable Under Test\n\n- variable:\n- why this matters:\n- what is out of scope:\n\n## Candidate Count\n\n- count:\n- ids: v1, v2, v3\n\n## Candidates\n\n| ID | Variable setting | Output location | Verification command | Notes |\n| --- | --- | --- | --- | --- |\n| v1 | | | | |\n| v2 | | | | |\n| v3 | | | | |\n\n## Review Criteria\n\nCompare candidates on:\n\n1. passes verification\n2. preserves invariants\n3. smallest durable change\n4. easiest integration path\n5. clearest rollback path\n```\n\n### Example: Billing Webhook Duplicate Processing\n\n```markdown\n# Variation Matrix\n\n## Goal\n\nPrevent duplicate processing of paid billing webhook events.\n\n## Invariants\n\n- Provider webhook contract stays fixed.\n- Database schema stays fixed for this round.\n- Existing invoice state transitions stay compatible.\n- Same verification command: `pnpm test billing-webhook -- --runInBand && pnpm build`.\n\n## Variable Under Test\n\nIdempotency strategy.\n\n## Candidates\n\n| ID | Variable setting | Output location | Verification command |\n| --- | --- | --- | --- |\n| v1 | provider event id guard | `../variation-<run-id>/v1` | `pnpm test billing-webhook -- --runInBand && pnpm build` |\n| v2 | invoice-level processing lock | `../variation-<run-id>/v2` | `pnpm test billing-webhook -- --runInBand && pnpm build` |\n| v3 | webhook processing ledger | `../variation-<run-id>/v3` | `pnpm test billing-webhook -- --runInBand && pnpm build` |\n\n## Review Criteria\n\nWhich strategy prevents duplicate invoice processing with the smallest durable change?\n```\n\n## Start From The Section 5 Seed\n\nUse Prompt Builder to save the base prompt and launch JSON under the variation run.\n\n```bash\nRUN_ID=\"billing-webhook-$(date +%Y%m%d-%H%M%S)\"\nROOT=\"artifacts/variations/$RUN_ID\"\nmkdir -p \"$ROOT\"/{prompts,launch,logs,review,decisions}\nmkdir -p \"$ROOT\"/candidates/{v1,v2,v3}\n\nPROMPT='Generate three controlled fixes for duplicate billing webhook processing. Keep the provider contract and database schema fixed. Vary only the idempotency strategy. Each option must name files, tests, risks, and rollback notes.'\n\np --print-prompt \"$PROMPT\" \\\n  > \"$ROOT/prompts/base.prompt.md\"\n\np --print-launch-json \"$PROMPT\" \\\n  > \"$ROOT/launch/base.launch.json\"\n\ntest -s \"$ROOT/prompts/base.prompt.md\" && echo \"base-prompt:OK\"\njq '.mode, .prompt' \"$ROOT/launch/base.launch.json\"\n```\n\nSave the matrix next to the seed:\n\n```bash\ncat > \"$ROOT/matrix.md\" <<'EOF'\n# Variation Matrix\n\n## Goal\n\nPrevent duplicate processing of paid billing webhook events.\n\n## Invariants\n\n- Provider webhook contract stays fixed.\n- Database schema stays fixed.\n- Existing invoice state transitions stay compatible.\n- Same verification command: `pnpm test billing-webhook -- --runInBand && pnpm build`.\n\n## Variable Under Test\n\nIdempotency strategy.\n\n## Candidate Count\n\n- count: 3\n- ids: v1, v2, v3\n\n## Candidates\n\n| ID | Variable setting | Output location | Verification command | Notes |\n| --- | --- | --- | --- | --- |\n| v1 | provider event id guard | `../variation-<run-id>/v1` | `pnpm test billing-webhook -- --runInBand && pnpm build` | |\n| v2 | invoice-level processing lock | `../variation-<run-id>/v2` | `pnpm test billing-webhook -- --runInBand && pnpm build` | |\n| v3 | webhook processing ledger | `../variation-<run-id>/v3` | `pnpm test billing-webhook -- --runInBand && pnpm build` | |\n\n## Review Criteria\n\n- prevents duplicate processing\n- preserves provider contract\n- keeps rollback simple\n- passes the same verification command\nEOF\n```\n\nConfirm the setup:\n\n```bash\nfind \"$ROOT\" -maxdepth 3 -type d | sort\ntest -s \"$ROOT/matrix.md\" && echo \"matrix:OK\"\ntest -s \"$ROOT/prompts/base.prompt.md\" && echo \"base-prompt:OK\"\ntest -s \"$ROOT/launch/base.launch.json\" && echo \"launch-json:OK\"\n```\n\n## Save Repo State Before Fan-Out\n\nBefore parallel code edits, save the current state.\n\n```bash\ngit status --short | tee \"$ROOT/review/git-status-before.txt\"\ngit diff > \"$ROOT/review/dirty-before.patch\"\ngit diff --staged > \"$ROOT/review/staged-before.patch\"\n```\n\nIf the repo is dirty, choose one:\n\n| State | Safe Next Move |\n| --- | --- |\n| intentional local work | commit or stash before fan-out |\n| unrelated local work | move it out of the candidate path |\n| generated files only | clean or save them under `artifacts/` |\n| unsure | stop and inspect before launching candidates |\n\nDo not fan out code edits from unknown dirty state.\n\n## Choose Isolation\n\nParallel candidates must not overwrite each other.\n\n| Isolation Option | Use When | Example |\n| --- | --- | --- |\n| copied prompt/output folders | candidates are plans, docs, prompts, or generated artifacts | `artifacts/variations/<run-id>/candidates/v1` |\n| branch | edits are small and reviewed one at a time | `git switch -c variation/<run-id>-v1` |\n| git worktree | candidates need parallel repo edits | `git worktree add ../variation-<run-id>/v1 -b variation/<run-id>-v1` |\n| directory copy | no git worktree support, but file edits must be separated | `cp -R app app-v1` |\n| feature flag | candidates can coexist in one app behind flags | `CHECKOUT_VARIANT=v1` |\n| unique process state | candidates run services | `PORT=3101`, `PORT=3102`, `PORT=3103` |\n\nFor code edits, prefer worktrees:\n\n```bash\nBASE=\"$(git rev-parse --show-toplevel)\"\nPARENT=\"$(dirname \"$BASE\")/variation-$RUN_ID\"\n\ngit -C \"$BASE\" worktree add \"$PARENT/v1\" -b \"variation/$RUN_ID-v1\"\ngit -C \"$BASE\" worktree add \"$PARENT/v2\" -b \"variation/$RUN_ID-v2\"\ngit -C \"$BASE\" worktree add \"$PARENT/v3\" -b \"variation/$RUN_ID-v3\"\n\ngit -C \"$BASE\" worktree list | tee \"$ROOT/review/worktrees.txt\"\n```\n\n## Build Candidate Prompts\n\nStart with the same base prompt. Add only the candidate setting.\n\n```bash\nfor id in v1 v2 v3; do\n  cp \"$ROOT/prompts/base.prompt.md\" \"$ROOT/prompts/$id.prompt.md\"\ndone\n\ncat >> \"$ROOT/prompts/v1.prompt.md\" <<'EOF'\nCandidate override:\n- candidate id: v1\n- variable: idempotency strategy\n- setting: provider event id guard\n- do not change any other dimension\nEOF\n\ncat >> \"$ROOT/prompts/v2.prompt.md\" <<'EOF'\nCandidate override:\n- candidate id: v2\n- variable: idempotency strategy\n- setting: invoice-level processing lock\n- do not change any other dimension\nEOF\n\ncat >> \"$ROOT/prompts/v3.prompt.md\" <<'EOF'\nCandidate override:\n- candidate id: v3\n- variable: idempotency strategy\n- setting: webhook processing ledger\n- do not change any other dimension\nEOF\n\nfor id in v1 v2 v3; do\n  test -s \"$ROOT/prompts/$id.prompt.md\" && echo \"$id prompt:OK\"\ndone\n```\n\nFor checkout UI integration, the same shape works:\n\n```text\nvariable: UI integration strategy\nv1 setting: inline payment method selector in checkout form\nv2 setting: account drawer payment method selector\nv3 setting: review-step payment method selector\n```\n\nKeep database contracts, provider APIs, security constraints, and verification fixed unless those are the chosen variable.\n\n## Fan-Out\n\nUse the same launch shape for every candidate.\n\nLocal background shape:\n\n```bash\nGEN=\"codex\"\n\nfor id in v1 v2 v3; do\n  (\n    cd \"$PARENT/$id\"\n    \"$GEN\" \"$(cat \"$ROOT/prompts/$id.prompt.md\")\"\n  ) > \"$ROOT/logs/$id.generate.log\" 2>&1 &\ndone\n\nwait\n```\n\nVisible pane shape:\n\n```bash\ncmux-run-surface \"cd '$PARENT/v1' && codex \\\"$(cat '$ROOT/prompts/v1.prompt.md')\\\"\"\ncmux-run-surface \"cd '$PARENT/v2' && codex \\\"$(cat '$ROOT/prompts/v2.prompt.md')\\\"\"\ncmux-run-surface \"cd '$PARENT/v3' && codex \\\"$(cat '$ROOT/prompts/v3.prompt.md')\\\"\"\n```\n\nWhat to preserve:\n\n```text\nsame base prompt\nsame invariants\nsame launch shape\none isolated lane per candidate\none log per candidate\n```\n\n## Verify Every Candidate\n\nRun the same verification command for every candidate.\n\n```bash\nVERIFY='pnpm test billing-webhook -- --runInBand && pnpm build'\n: > \"$ROOT/review/verification.tsv\"\n\nfor id in v1 v2 v3; do\n  (\n    cd \"$PARENT/$id\"\n    bash -lc \"$VERIFY\"\n  ) > \"$ROOT/logs/$id.verify.log\" 2>&1\n  status=$?\n  printf '%s\\t%s\\t%s\\n' \"$id\" \"$status\" \"$VERIFY\" \\\n    >> \"$ROOT/review/verification.tsv\"\ndone\n\ncolumn -t -s $'\\t' \"$ROOT/review/verification.tsv\"\n```\n\nSave diff material for review:\n\n```bash\nfor id in v1 v2 v3; do\n  git -C \"$PARENT/$id\" diff --stat \\\n    > \"$ROOT/review/$id.diffstat.txt\"\n  git -C \"$PARENT/$id\" diff \\\n    > \"$ROOT/review/$id.diff.patch\"\ndone\n```\n\nFor UI candidates, also save screenshots:\n\n```bash\nmkdir -p \"$ROOT/review/screenshots\"\n# Save:\n# \"$ROOT/review/screenshots/v1.png\"\n# \"$ROOT/review/screenshots/v2.png\"\n# \"$ROOT/review/screenshots/v3.png\"\n```\n\n## Review Surface\n\nUse the lightest surface that makes comparison honest.\n\n| Surface | Use When | Save |\n| --- | --- | --- |\n| simple matrix | text, plans, test results, diffs | `review/comparison.md` |\n| diff review | code changes matter most | `review/v*.diff.patch` |\n| screenshots | UI integration or visual changes | `review/screenshots/` |\n| test results | correctness is the main gate | `logs/*.verify.log`, `review/verification.tsv` |\n| structured feedback | choice needs to be preserved exactly | `decisions/selection.md` or saved JSON |\n\nCreate comparison notes:\n\n```bash\ncat > \"$ROOT/review/comparison.md\" <<EOF\n# Variation Comparison\n\n## Goal\n\nPrevent duplicate processing of paid billing webhook events.\n\n## Variable Under Test\n\nIdempotency strategy.\n\n## Verification\n\n| Candidate | Status | Log |\n| --- | --- | --- |\n| v1 | see \\`verification.tsv\\` | \\`$ROOT/logs/v1.verify.log\\` |\n| v2 | see \\`verification.tsv\\` | \\`$ROOT/logs/v2.verify.log\\` |\n| v3 | see \\`verification.tsv\\` | \\`$ROOT/logs/v3.verify.log\\` |\n\n## Diff Review\n\n| Candidate | Diff Stat | Full Diff |\n| --- | --- | --- |\n| v1 | \\`$ROOT/review/v1.diffstat.txt\\` | \\`$ROOT/review/v1.diff.patch\\` |\n| v2 | \\`$ROOT/review/v2.diffstat.txt\\` | \\`$ROOT/review/v2.diff.patch\\` |\n| v3 | \\`$ROOT/review/v3.diffstat.txt\\` | \\`$ROOT/review/v3.diff.patch\\` |\n\n## Review Criteria\n\n- prevents duplicate processing\n- preserves provider contract\n- keeps rollback simple\n- passes the same verification command\n- minimizes unnecessary code movement\n\n## Notes\n\n| Candidate | Strengths | Risks | Keep / Drop |\n| --- | --- | --- | --- |\n| v1 | | | |\n| v2 | | | |\n| v3 | | | |\nEOF\n```\n\n## Decision Outcomes\n\nEnd every review with one action.\n\n| Outcome | Meaning | Next Step |\n| --- | --- | --- |\n| Pick | choose one candidate as-is | polish and verify selected candidate |\n| Combine | use one primary candidate plus named pieces from others | merge only named pieces, then verify |\n| Refine | keep one candidate and apply specific feedback | apply bounded edits, then verify |\n| Expand | run another controlled round on a new dimension | write a new matrix |\n| Reject | throw away the set | rewrite the prompt, matrix, or verification |\n\nSaved decision shape:\n\n```bash\ncat > \"$ROOT/decisions/selection.md\" <<'EOF'\n# Saved Decision\n\n- outcome:\n- primary candidate:\n- secondary candidate ids:\n- decision:\n- why:\n- rejected candidates:\n- required follow-up:\n- final verification command:\n\n## Review Notes\n\n- v1:\n- v2:\n- v3:\n\n## Continue Prompt\n\nContinue from this saved decision.\nDo not reopen the entire search.\nPreserve the selected candidate.\nApply only the named feedback.\nRun final verification and save the result.\nEOF\n```\n\nUse the saved decision as the next prompt material:\n\n```bash\ncat \"$ROOT/decisions/selection.md\" \\\n  | p --stdin --print-prompt \\\n  \"Use this saved decision to converge the variation set. Keep scope narrow and run the required verification.\" \\\n  > \"$ROOT/prompts/converge.prompt.md\"\n\ntest -s \"$ROOT/prompts/converge.prompt.md\" && echo \"converge-prompt:OK\"\n```\n\n## Ask The Agent This\n\nCreate a variation matrix:\n\n```text\nCreate a controlled variation matrix for adding saved payment methods to checkout.\n\nUse exactly one variable: UI integration strategy. Keep database schema,\nprovider API, auth behavior, and verification fixed. Propose three candidates,\nthe same verification command for each, isolation strategy, review criteria,\nand the saved decision file shape.\n```\n\nGenerate candidate prompts:\n\n```text\nUsing this base Prompt Builder prompt, create three candidate prompts.\n\nEach candidate must preserve the same goal, invariants, verification command,\nand review criteria. Only vary the idempotency strategy for the billing webhook:\nprovider event id guard, invoice-level processing lock, and webhook processing\nledger. Do not introduce a second variable.\n```\n\nReview a finished variation set:\n\n```text\nReview this variation run.\n\nInspect the matrix, candidate prompts, verification logs, diffs, and comparison\nnotes. Decide Pick, Combine, Refine, Expand, or Reject. If Combine, choose one\nprimary candidate and name the exact pieces to take from the others.\n```\n\nConverge after selection:\n\n```text\nUse this saved decision to converge the variation set.\n\nDo not reopen the entire search. Preserve the selected candidate, apply only\nthe named feedback, run the final verification command, and save the result.\n```\n\n## What To Confirm / How To Know It Worked\n\n| Goal | Confirmation |\n| --- | --- |\n| base prompt saved | `test -s \"$ROOT/prompts/base.prompt.md\"` |\n| launch shape saved | `test -s \"$ROOT/launch/base.launch.json\"` |\n| matrix exists | `test -s \"$ROOT/matrix.md\"` |\n| one variable named | matrix has one `Variable Under Test` |\n| candidates isolated | each candidate has a distinct branch/worktree/directory |\n| same verification | `verification.tsv` shows the same command for every candidate |\n| logs saved | `find \"$ROOT/logs\" -type f | sort` |\n| diff/review material saved | `find \"$ROOT/review\" -type f | sort` |\n| comparison complete | `test -s \"$ROOT/review/comparison.md\"` |\n| decision saved | `test -s \"$ROOT/decisions/selection.md\"` |\n| convergence prompt saved | `test -s \"$ROOT/prompts/converge.prompt.md\"` |\n\n## If It Goes Wrong\n\n### Candidates Changed Multiple Variables\n\nStop and rewrite the matrix.\n\n```text\nIf the candidate changes UI, database schema, and test strategy, it is not a controlled variation.\n```\n\nRecovery:\n\n```text\nKeep one chosen variable.\nMove every other change into invariants or out-of-scope.\nRegenerate candidate prompts.\n```\n\n### Verification Differs Per Candidate\n\nThe comparison is weak if every candidate gets a different proof command.\n\nRecovery:\n\n```text\nPick one verification command before generation.\nIf a candidate needs a different proof, that is evidence for a new round.\n```\n\n### Repo Was Dirty Before Fan-Out\n\nDirty state is not forbidden. Unknown dirty state is the problem.\n\nRecovery:\n\n```bash\ngit status --short\ngit diff\ngit diff --staged\n```\n\nThen commit, stash, clean, or explicitly record what should carry into every candidate.\n\n### Best Idea Is Split Across Candidates\n\nUse `Combine`, not vague merging.\n\n```text\nprimary candidate: v2\ntake from v1: rollback guard\ntake from v3: test fixture\nforbidden: unrelated renames\n```\n\nThen run final verification after convergence.\n\n### All Candidates Fail\n\nDo not pretend one failed candidate won.\n\nUse:\n\n```text\nReject\n```\n\nor:\n\n```text\nExpand with a narrower matrix\n```\n\nSave what the failures proved before starting the next round.\n\n## References And Resources\n\n- Prompt Builder seed prompt: `p --print-prompt`\n- Prompt Builder launch JSON: `p --print-launch-json`\n- Local run folder: `artifacts/variations/<run-id>/`\n- Candidate isolation: `git worktree`\n- Repo state checks: `git status --short`, `git diff`, `git diff --staged`\n- Review artifacts: `review/verification.tsv`, `review/comparison.md`, `decisions/selection.md`\n\n## Operational boundaries\n\n- The fan-out snippets describe the launch shape, not a universally executable harness. Resolve `$ROOT` to an absolute artifact directory before changing into worktrees; validate nested quoting and the installed Codex non-interactive invocation.\n- A candidate process exiting or `wait` returning is not passing proof. Capture each generation exit status and run the same project-valid verification command in every lane.\n- Git worktrees start from committed state. A plain `git diff` omits staged, untracked, and already committed candidate changes; preserve the actual baseline and all relevant review evidence.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
}
