{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "foundations-throwaway-variants-playbook",
  "slug": "throwaway-variants-playbook",
  "title": "Throwaway route variants playbook",
  "summary": "Web developers often need to compare UI directions in the real app, against real routing, styling, auth, responsive behavior, and browser state. Throwaway route variants give an AI agent a concrete way to generate options quickly, prove them in localhost, promote one winner, and remove the experimental surface before it becomes maintenance debt.",
  "category": "Planning",
  "tags": [
    "design.md",
    "source of truth",
    "variants",
    "playbook",
    "prompts"
  ],
  "sources": [
    {
      "label": "Agent foundations: Trust current source and capture design decisions (authorized access required)",
      "url": "https://codex-workshop-followup.pages.dev/lesson-04.html"
    }
  ],
  "sourceUnits": [
    "scenarios/topics.mjs#throwaway-variants",
    "scenarios/throwaway-variants.json#audienceFit",
    "toolkit/codex-skills/throwaway-route-variants/SKILL.md",
    "scenarios/throwaway-variants.json#scenarios/0",
    "scenarios/throwaway-variants.json#scenarios/1",
    "scenarios/throwaway-variants.json#scenarios/2",
    "scenarios/throwaway-variants.json#implementationNotes",
    "scenarios/throwaway-variants.json#notTaughtOrAvoid/1",
    "scenarios/throwaway-variants.json#notTaughtOrAvoid/2",
    "scenarios/throwaway-variants.json#notTaughtOrAvoid/3",
    "scenarios/throwaway-variants.json#notTaughtOrAvoid/4",
    "scenarios/throwaway-variants.json#notTaughtOrAvoid/5",
    "scenarios/throwaway-variants.json#notTaughtOrAvoid/6",
    "scenarios/throwaway-variants.json#notTaughtOrAvoid/7",
    "scenarios/throwaway-variants.json#agentReferences"
  ],
  "collection": "foundations",
  "categoryId": "planning",
  "wordCount": 2324,
  "url": "/topics/foundations-throwaway-variants-playbook/",
  "markdownUrl": "/markdown/foundations-throwaway-variants-playbook.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/foundations-throwaway-variants-playbook.json",
  "headings": [
    {
      "id": "reusable-skill",
      "text": "Reusable skill",
      "level": 2
    },
    {
      "id": "scenarios",
      "text": "Scenarios",
      "level": 2
    },
    {
      "id": "landing-page-direction-sprint",
      "text": "Landing page direction sprint",
      "level": 3
    },
    {
      "id": "agent-brief",
      "text": "Agent brief",
      "level": 4
    },
    {
      "id": "implementation-references",
      "text": "Implementation references",
      "level": 4
    },
    {
      "id": "browser-verification",
      "text": "Browser verification",
      "level": 4
    },
    {
      "id": "definition-of-done",
      "text": "Definition of done",
      "level": 4
    },
    {
      "id": "failure-modes-and-mitigations",
      "text": "Failure modes and mitigations",
      "level": 4
    },
    {
      "id": "authenticated-onboarding-alternatives",
      "text": "Authenticated onboarding alternatives",
      "level": 3
    },
    {
      "id": "agent-brief-2",
      "text": "Agent brief",
      "level": 4
    },
    {
      "id": "implementation-references-2",
      "text": "Implementation references",
      "level": 4
    },
    {
      "id": "browser-verification-2",
      "text": "Browser verification",
      "level": 4
    },
    {
      "id": "definition-of-done-2",
      "text": "Definition of done",
      "level": 4
    },
    {
      "id": "failure-modes-and-mitigations-2",
      "text": "Failure modes and mitigations",
      "level": 4
    },
    {
      "id": "responsive-dashboard-density-bake-off",
      "text": "Responsive dashboard density bake-off",
      "level": 3
    },
    {
      "id": "agent-brief-3",
      "text": "Agent brief",
      "level": 4
    },
    {
      "id": "implementation-references-3",
      "text": "Implementation references",
      "level": 4
    },
    {
      "id": "browser-verification-3",
      "text": "Browser verification",
      "level": 4
    },
    {
      "id": "definition-of-done-3",
      "text": "Definition of done",
      "level": 4
    },
    {
      "id": "failure-modes-and-mitigations-3",
      "text": "Failure modes and mitigations",
      "level": 4
    },
    {
      "id": "implementation-notes",
      "text": "Implementation notes",
      "level": 2
    },
    {
      "id": "boundaries-and-caveats",
      "text": "Boundaries and caveats",
      "level": 2
    },
    {
      "id": "agent-reference-map",
      "text": "Agent reference map",
      "level": 2
    },
    {
      "id": "throwaway-route-variants-skill",
      "text": "Throwaway route variants skill",
      "level": 3
    },
    {
      "id": "lesson-04-validated-references",
      "text": "Lesson 04 validated references",
      "level": 3
    },
    {
      "id": "lesson-04-validation-guardrails",
      "text": "Lesson 04 validation guardrails",
      "level": 3
    },
    {
      "id": "lesson-04-interactive-checklist",
      "text": "Lesson 04 interactive checklist",
      "level": 3
    },
    {
      "id": "local-dev-command",
      "text": "Local dev command",
      "level": 3
    },
    {
      "id": "cmux-state-inspection",
      "text": "CMUX state inspection",
      "level": 3
    },
    {
      "id": "cmux-pane-list",
      "text": "CMUX pane list",
      "level": 3
    }
  ],
  "markdown": "# Throwaway route variants playbook\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nWeb developers often need to compare UI directions in the real app, against real routing, styling, auth, responsive behavior, and browser state. Throwaway route variants give an AI agent a concrete way to generate options quickly, prove them in localhost, promote one winner, and remove the experimental surface before it becomes maintenance debt.\n\n[Core principles](/topics/foundations-source-truth-and-design/)\n\n## Reusable skill\n\nInstall as `~/.agents/skills/throwaway-route-variants/SKILL.md`, then restart Codex.\n\n```markdown\n---\nname: throwaway-route-variants\ndescription: Trigger when exploring UI/layout directions and you want fast comparison without a permanent component catalog — generate several route-level variants in-app, review, keep one, delete the rest. Do NOT use when a maintained design system is required.\n---\n\n# Throwaway route variants\n\nThe anti-Storybook move: generate several route-level UI variants inside the running app, compare them, keep the winner, and DELETE the losers. Favors shipping momentum over a maintained catalog. These variants are explicitly disposable.\n\n## Steps\n\n1. Generate 5 route-level variants of the target UI INSIDE the running app — each variant is its own route (e.g. `/variant-a`, `/variant-b`, ...), not a permanent component.\n\n2. Add simple left/right navigation between the variants so the human can flip through and compare them live.\n\n3. Let the human pick the winner.\n\n4. DELETE the losing routes/variants — do not keep them around as a catalog.\n\n## Guardrails\n- Variants are explicitly disposable; this favors shipping momentum over a maintained component catalog.\n- Do NOT use when a maintained design system / permanent component library is required.\n```\n\n## Scenarios\n\n### Landing page direction sprint\n\n**Role:** As a frontend product engineer working in a Next.js-style marketing app\n\nThe team has a design.md for a new homepage, but the visual direction is still unsettled before a stakeholder review. The app already has shared typography, buttons, cards, and layout primitives, and the developer wants to compare several real routes in localhost instead of asking for more static mockups or setting up Storybook.\n\n> As a frontend product engineer, I want an agent to create disposable homepage route variants from the current code and design.md, so that I can review real browser-rendered options, pick one, and ship without keeping a permanent variant catalog.\n\n#### Agent brief\n\n```text\nUse the throwaway-route-variants skill only. First inspect the current routing structure, package.json scripts, existing homepage route, shared components, and design.md if present. Do not trust stale memory about the app structure. Create 5 temporary route-level variants of the homepage inside the app using the existing routing convention, for example /variant-a through /variant-e or the equivalent framework-native paths. Reuse existing components where practical, but keep variant-specific layout/styling isolated to the temporary routes so cleanup is simple. Add simple left/right navigation between variants, including visible Previous/Next controls and keyboard ArrowLeft/ArrowRight handling if that fits the app. Run the repo's actual dev command from package.json, usually npm run dev, pnpm dev, or bun dev. Prove every variant renders in the browser at localhost. After the human chooses a winner, promote only that implementation to the real homepage route, delete every losing variant route and temporary navigation wrapper, then run the relevant lint/typecheck/build command from package.json. Expected output: a short comparison table of the 5 variants, the chosen route, browser proof notes, commands run, and a final git diff summary showing only the promoted implementation remains.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-throwaway-variants-playbook/)\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n```text\npackage.json scripts in the target repo\n```\n\n```text\ndesign.md in the target repo if present\n```\n\n```text\napp/page.tsx, pages/index.tsx, src/routes, or the repo's current homepage route discovered by inspection\n```\n\n#### Browser verification\n\nUse the running local dev server as the proof surface. In a CMUX browser pane or normal local browser, open the first temporary route, then use the variant navigation controls or ArrowLeft/ArrowRight to cycle through all variants. If using an agent-browser-style workflow, collect an accessibility snapshot for each route, evaluate window.location.pathname after navigation, and capture screenshots or concise visual notes for the human review.\n\n#### Definition of done\n\n- All temporary routes render successfully in localhost using the repo's real dev command.\n- Browser proof exists for every variant: screenshots, accessibility snapshots, or explicit route-by-route notes with no console-blocking runtime errors.\n- The selected variant is promoted to the real homepage route.\n- All losing route variants and temporary navigation scaffolding are deleted.\n- The final diff does not leave behind a Storybook-like catalog, hidden demo routes, or unused variant components.\n\n#### Failure modes and mitigations\n\n- Mistake: the agent creates polished variants but leaves all 5 routes in the app. Mitigation: require a final cleanup pass and verify with git diff plus route search for variant-a, variant-b, variant-c, variant-d, and variant-e.\n- Mistake: the agent rewrites shared components so every variant leaks into production styling. Mitigation: keep variant-specific changes route-local until the winner is chosen, then promote deliberately.\n\n### Authenticated onboarding alternatives\n\n**Role:** As a full-stack web developer responsible for signup and first-run onboarding\n\nA SaaS app has a working auth flow, but the post-signup onboarding page feels confusing. The team wants to compare several onboarding layouts in the real authenticated shell without risking the existing auth guard, database writes, or production onboarding state machine.\n\n> As a full-stack web developer, I want an agent to create disposable authenticated onboarding route variants that reuse the current app shell and safe fixture data, so that I can compare real UX options without breaking auth or business logic.\n\n#### Agent brief\n\n```text\nUse the throwaway-route-variants skill for UI exploration only. Inspect the current auth guard, onboarding route, layout shell, data-loading pattern, and package.json scripts before editing. Do not change authentication logic, database schema, real onboarding mutations, or production redirects. Create 3 to 5 temporary route-level onboarding variants under a clearly disposable dev-only path, such as /onboarding/variant-a through /onboarding/variant-e or the framework's equivalent. Each variant should reuse the current authenticated shell and existing components, but it may use safe fixture data or read-only mocks when live data would create side effects. Add simple Previous/Next navigation between variants. Run the dev server using the actual package.json script and verify the routes in a browser. If auth is required, document the exact login path or test-user setup needed; do not assume cookies are shared with a browser agent. After the human chooses a winner, promote only that UI to the real onboarding route and delete every temporary variant path. Expected output: route list, auth assumptions, browser verification notes, commands run, cleanup confirmation, and final diff summary.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-throwaway-variants-playbook/)\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n```text\nCurrent auth guard and onboarding route discovered from source inspection\n```\n\n```text\npackage.json scripts in the target repo\n```\n\n```text\nExisting app shell/layout components\n```\n\n```text\nExisting onboarding components, forms, and safe fixture or mock-data patterns\n```\n\n#### Browser verification\n\nUse a browser proof that respects auth reality. In a CMUX browser pane or agent-browser-style session, start from the documented login path, click/fill the test login only if the repo provides safe credentials or a local fixture path, then visit each onboarding variant. Capture an accessibility snapshot showing the page heading, primary CTA, progress indicator, and navigation controls. If login is not available, verify the variant routes with a safe mocked/read-only local route and state that authenticated production behavior was not mutated.\n\n#### Definition of done\n\n- Temporary onboarding variants are reachable in the local app without changing auth guards or production redirects.\n- Each variant has browser proof showing the authenticated shell or clearly documented safe mock shell.\n- No database schema, mutation path, or real onboarding state transition is changed for the experiment.\n- The selected UI is promoted to the real onboarding route after human selection.\n- All temporary onboarding variant routes and navigation wrappers are removed.\n\n#### Failure modes and mitigations\n\n- Mistake: the agent makes the variant work by weakening the auth guard. Mitigation: explicitly forbid auth changes and require the final diff to show no auth-guard or session-validation edits unless the human requested them separately.\n- Mistake: the agent assumes the browser agent has the developer's cookies. Mitigation: require an explicit login path, safe test account instructions, or a read-only mock route for browser proof.\n\n### Responsive dashboard density bake-off\n\n**Role:** As a senior frontend engineer cleaning up a dense admin dashboard\n\nA dashboard route has grown cluttered after several feature additions. Product wants to compare a compact data-heavy layout, a guided summary layout, and a card-based layout before committing to a redesign. The current code has real components and data boundaries that should be treated as source of truth.\n\n> As a senior frontend engineer, I want an agent to generate disposable dashboard route variants using the current code as source of truth, so that I can compare density, hierarchy, and responsive behavior in-browser before replacing the real dashboard route.\n\n#### Agent brief\n\n```text\nUse the throwaway-route-variants skill. Inspect the current dashboard route, layout components, data-fetching boundaries, responsive utilities, and package.json scripts. Create exactly 3 temporary dashboard route variants: one compact/data-dense, one guided/summary-first, and one card-based. Keep data access read-only and preserve existing component contracts. Add simple left/right navigation among the 3 variants. Run the local dev server with the actual package.json command, then verify desktop and narrow viewport behavior in a browser. Do not create Storybook stories, a permanent examples directory, or a dashboard variant gallery. After human selection, promote the winner to the real dashboard route and delete the 3 temporary routes. Expected output: variant intent summary, browser proof at desktop and mobile/narrow viewport, commands run, selected winner, and cleanup proof from git diff or route search.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-throwaway-variants-playbook/)\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n```text\nCurrent dashboard route discovered from source inspection\n```\n\n```text\nCurrent shared dashboard/card/table/chart components\n```\n\n```text\npackage.json scripts in the target repo\n```\n\n#### Browser verification\n\nUse browser verification because layout density and responsiveness cannot be proven from source alone. In a CMUX browser pane, local browser, Playwright-backed check, or agent-browser-style workflow, open each temporary dashboard route at a desktop width and a narrow mobile-like width. Use evaluate to record viewport width and current pathname, take screenshots or visual notes, and verify that Previous/Next navigation reaches all three variants without a runtime error.\n\n#### Definition of done\n\n- Three route-level dashboard variants exist temporarily and match the requested density directions.\n- Desktop and narrow-viewport browser proof is captured for all variants.\n- Existing data contracts remain read-only and stable during the experiment.\n- Only the selected dashboard implementation remains after cleanup.\n- A final route search or git diff proves temporary variants were removed.\n\n#### Failure modes and mitigations\n\n- Mistake: the agent judges responsiveness from code without opening the browser. Mitigation: require viewport-based browser proof for every variant before selection.\n- Mistake: the agent turns route variants into a permanent demo gallery. Mitigation: define the routes as disposable from the start and require post-selection deletion as part of done.\n\n## Implementation notes\n\n- Start by inspecting the live repo. Routing conventions, package scripts, app shell, auth boundaries, and component names must come from current code, not memory.\n- Make the temporary routes obvious and searchable. Names like variant-a, variant-b, and variant-c are boring on purpose because cleanup is easier.\n- Keep variant-specific implementation route-local until the winner is selected. Promote only the winning idea into the real route after review.\n- Browser proof matters for this technique. A successful typecheck is not enough when the decision is visual hierarchy, flow, density, responsive behavior, or auth-shell fit.\n- The final cleanup is not optional. The technique only works if the losing variants are deleted instead of becoming a second design system.\n- When an authenticated browser proof is needed, spell out the login/test-user path or use safe local fixture data. Do not assume a browser agent has access to the developer's existing cookies.\n\n## Boundaries and caveats\n\n- Do not build or recommend a full Storybook-style maintained catalog for these experiments.\n- Do not keep rejected variants as hidden routes, examples, or future inspiration unless the human explicitly asks for a maintained catalog.\n- Do not rely on stale project memory when route structure or implementation details matter.\n- Do not scrape or copy existing websites as design source material; the taught design workflow used generated visual inspiration and design.md.\n- Do not introduce removed this workflow items as implementation requirements: Codex Sandbox and Approvals, AGENTS.md, Impeccable, Beads, Chrome DevTools MCP, or Deep Wiki Map.\n- Do not use YOLO, skip-trust, or approval-bypass aliases as part of this playbook.\n- Do not present large-context snapshots as the proven route-variant workflow; in this lesson they were framed as a possible escape hatch, not the demonstrated technique.\n\n## Agent reference map\n\n### Throwaway route variants skill\n\nPrimary workflow contract for this topic: generate route-level variants in the running app, add simple navigation, let the human pick, then delete losers.\n\n[Open reference](/topics/foundations-throwaway-variants-playbook/)\n\n### Lesson 04 validated references\n\nGrounding source for the taught concepts: code as source of truth, design.md from generated inspiration, and disposable route variants.\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n### Lesson 04 validation guardrails\n\nUse this to avoid reintroducing tools and claims that were removed as only mentioned or not taught in this section.\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n### Lesson 04 interactive checklist\n\nUseful for the implementation shape: prompt the agent to inspect current files, generate route-level variants, review in browser, promote one, and delete temporary routes.\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n### Local dev command\n\nThe agent should inspect the target repo and run the real dev, lint, typecheck, and build scripts rather than guessing commands.\n\n```text\npackage.json\n```\n\n### CMUX state inspection\n\nWhen working in CMUX, the agent can inspect the current pane/workspace before opening or using browser/terminal panes for proof.\n\n```text\ncmux --json tree\n```\n\n### CMUX pane list\n\nUse when coordinating a terminal pane running the dev server and a browser pane used for route review.\n\n```text\ncmux list-panes\n```"
}
