Oracle handoff for a huge codebase question
Working web developers routinely hit questions that are too broad for a local coding-agent thread: auth architecture, route ownership, stale data bugs, migration blast radius, or a tangled UI flow. Oracle handoff keeps Codex focused on local implementation while a browser ChatGPT Pro session reads the huge PackX bundle and returns a plan the agent can verify in the running app.
Unblock a tangled Next.js auth redirect bug
As a senior full-stack web developer owning a Next.js app
A production-like local Next.js app has a login redirect loop that only appears after mixing middleware, server components, API route auth checks, and client-side session refresh. The issue spans many files, so asking Codex to read everything directly would burn the interactive session budget.
As a senior full-stack web developer, I want Codex to offload the broad auth-flow investigation through Oracle and PackX, so that Codex can spend its local context on implementing and verifying the fix instead of reading the whole repo.
You are my coding agent in this repo. Investigate the auth redirect loop by using the Oracle codebase handoff workflow, then implement only the locally verifiable fix. Do not skip the PackX preview. Create `.notes/` if needed. First run `packx --preview -s "Next.js auth redirect middleware session login callback API route"` and inspect the matched files and token estimate. If the scope is reasonable, run `packx -s "Next.js auth redirect middleware session login callback API route" -f markdown --no-interactive -o .notes/handoff-bundle.md`. Then send the bundle through Oracle browser mode with a 3-5 word kebab slug, and make the prompt start with the same bracketed slug on line 1: `ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[auth-redirect-loop]\n\nWe have a Next.js auth redirect loop. Read the attached PackX bundle and produce: 1) the likely root cause, 2) the exact files/functions to inspect first, 3) a minimal implementation plan, 4) local verification steps using the dev server/browser, and 5) risks or false leads to avoid. Do not propose unrelated rewrites." --slug "auth-redirect-loop" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md`. After Oracle returns, read `.notes/oracle-plan.md`, summarize the recommended fix in `.notes/auth-redirect-receipt.md`, implement the smallest safe change, then run the repo's existing typecheck/test/build command discovered from package scripts. Finally start the local dev server and verify the login flow in a browser.
Use the running local app as proof, not source-code confidence. In a CMUX browser pane or browser-agent workflow, open the dev server, capture an accessibility snapshot of the login page, click the sign-in control, fill the test credentials or scripted local auth fields, submit, and evaluate `window.location.pathname` plus visible authenticated UI text. Save a screenshot or browser transcript showing the flow reaches the expected post-login route without bouncing back to `/login`.
Implementation refs
- workshop-followup/toolkit/prompts/01-oracle-codebase-handoff-prompt.md
- workshop-followup/toolkit/codex-skills/oracle-codebase-handoff/SKILL.md
- workshop-followup/toolkit/bundles/code-oracle-packx.md
- packx --preview -s "Next.js auth redirect middleware session login callback API route"
- packx -s "Next.js auth redirect middleware session login callback API route" -f markdown --no-interactive -o .notes/handoff-bundle.md
- ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[auth-redirect-loop]\n\n<question>" --slug "auth-redirect-loop" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md
Done when
- .notes/oracle-plan.md exists and contains the browser-side Oracle recommendation
- .notes/auth-redirect-receipt.md records the selected fix, files changed, and why alternatives were rejected
- Repo verification command passes, such as test/typecheck/build from package scripts
- Browser proof shows login reaches the expected authenticated route without a redirect loop
- Git diff is limited to the auth-related fix and does not include `.notes/` artifacts
Failure modes
- Mistake: using Oracle before previewing the bundle, causing a bloated or irrelevant handoff. Mitigation: require `packx --preview` first and adjust the search topic before writing `.notes/handoff-bundle.md`.
- Mistake: implementing the whole Oracle plan as if it were guaranteed correct. Mitigation: treat `.notes/oracle-plan.md` as a plan, then implement the smallest locally verifiable change and prove it in the browser.
- Mistake: using a slug that Oracle rejects. Mitigation: use exactly 3-5 kebab words and start the prompt with `[same-slug]` followed by a blank line.
- Mistake: trusting unit tests for a browser-only redirect bug. Mitigation: require browser proof against the running dev server.
Find the real owner of a checkout state bug
As a product engineer maintaining a checkout funnel
A React or Remix checkout page loses cart state when the user changes shipping method, navigates back, or refreshes after payment intent creation. The logic is split across route loaders/actions, client state, server API handlers, and payment integration code.
As a product engineer, I want a huge-context Oracle pass to map the checkout state ownership and failure points, so that my local agent can make a targeted fix and prove the checkout flow in the browser.
You are my coding agent. Use Oracle + PackX only for the broad read-heavy diagnosis, then return to local implementation and verification. Create `.notes/` if needed. Run `packx --preview -s "checkout cart state shipping method payment intent loader action API"`. Review the preview for checkout routes, cart/session modules, API handlers, and payment-related files. If relevant, run `packx -s "checkout cart state shipping method payment intent loader action API" -f markdown --no-interactive -o .notes/handoff-bundle.md`. Then run `ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[checkout-state-owner]\n\nRead the attached checkout-related codebase bundle. Identify which layer should own checkout/cart state, where the current flow can lose state during shipping changes, browser back navigation, refresh, or payment intent creation, and propose the smallest fix. Return exact file/function references, a step-by-step implementation plan, and browser verification steps. Avoid broad architecture rewrites unless the current code makes a minimal fix unsafe." --slug "checkout-state-owner" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md`. Read the returned plan, write `.notes/checkout-handoff-receipt.md` with the chosen path, implement the minimal fix, then run existing tests/build. If the repo has no browser test, use the dev server plus a browser-agent or CMUX browser pane to verify the funnel manually and record evidence.
Use browser verification because this bug is about real user navigation. In the local app, open the checkout route, capture a snapshot of cart line items and total, click through shipping method changes, use back/forward navigation, refresh once after the payment-intent step if safe in the local/test environment, and evaluate the visible cart total plus any checkout state exposed in the page. Save a screenshot or transcript proving the cart survives the exact sequence.
Implementation refs
- workshop-followup/toolkit/codex-skills/oracle-codebase-handoff/SKILL.md
- workshop-followup/toolkit/bundles/oracle-codebase-handoff-skill.bundle.txt
- workshop-followup/toolkit/bundles/code-oracle-packx.md
- packx --preview -s "checkout cart state shipping method payment intent loader action API"
- packx -s "checkout cart state shipping method payment intent loader action API" -f markdown --no-interactive -o .notes/handoff-bundle.md
- ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[checkout-state-owner]\n\n<question>" --slug "checkout-state-owner" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md
Done when
- PackX preview was inspected before bundle creation
- .notes/oracle-plan.md contains a file/function-level checkout state diagnosis
- .notes/checkout-handoff-receipt.md names the selected minimal fix and verification sequence
- Existing repo checks pass
- Browser proof shows the checkout state survives shipping change, back navigation, and refresh in the local/test flow
Failure modes
- Mistake: asking Oracle for a generic checkout redesign. Mitigation: phrase the Oracle prompt around state ownership, exact failure paths, minimal fix, and browser proof.
- Mistake: including live secrets, customer data, or real payment credentials in logs or screenshots. Mitigation: use local/test data only and redact artifacts before saving.
- Mistake: letting Codex use Oracle for every small follow-up. Mitigation: use Oracle once for the broad read-heavy map, then continue locally unless another huge-codebase question appears.
- Mistake: verifying only the happy path. Mitigation: require the back/refresh/shipping-change sequence that reproduced the bug.
Map a legacy migration before touching code
As a tech lead planning a risky front-end migration
A large web app is moving one feature area from legacy pages to a newer app-router or component architecture. The team needs to know which files, routes, shared utilities, and tests are involved before assigning implementation work.
As a tech lead, I want an Oracle handoff to produce a migration map from the current codebase, so that the implementation agent can work from a grounded plan and avoid guessing across many files.
You are my coding agent. This is a read-heavy migration-mapping task, so use Oracle handoff first and do not edit source files until the returned plan is reviewed. Create `.notes/` if needed. Run `packx --preview -s "legacy feature migration routes components shared utilities tests"`. If the preview includes the expected legacy feature area, run `packx -s "legacy feature migration routes components shared utilities tests" -f markdown --no-interactive -o .notes/handoff-bundle.md`. Then run `ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[legacy-migration-map]\n\nRead the attached PackX bundle for a large web app migration. Produce an implementation-ready migration map: current entry points, route/page ownership, shared components/utilities, test/build commands to run, risky coupling points, safe first slice, and a plan -> implement -> verify sequence. Do not invent tools or recommend a broad rewrite; stay grounded in the attached code." --slug "legacy-migration-map" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md`. After Oracle returns, create `.notes/migration-slice-receipt.md` with the first safe slice, explicit files to edit, verification commands, and browser proof needed. Implement only that first slice if it is small enough; otherwise stop with the migration map and receipt for human review.
Browser proof is useful only after a concrete migration slice exists. For the planning-only phase, the right proof is `.notes/oracle-plan.md` plus a migration receipt. If implementing the first slice, open old and new routes in a local browser or CMUX browser pane, capture snapshots/screenshots of the same user-visible state, click the primary controls, and confirm the migrated route preserves the expected behavior.
Implementation refs
- workshop-followup/oracle/01-references.json
- workshop-followup/toolkit/prompts/01-oracle-codebase-handoff-prompt.md
- workshop-followup/toolkit/codex-skills/oracle-codebase-handoff/SKILL.md
- workshop-followup/toolkit/bundles/code-oracle-packx.md
- packx --preview -s "legacy feature migration routes components shared utilities tests"
- packx -s "legacy feature migration routes components shared utilities tests" -f markdown --no-interactive -o .notes/handoff-bundle.md
- ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[legacy-migration-map]\n\n<question>" --slug "legacy-migration-map" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md
Done when
- .notes/oracle-plan.md exists and maps entry points, route ownership, shared utilities, risks, and first safe slice
- .notes/migration-slice-receipt.md converts the Oracle recommendation into a local implementation decision
- No source files are changed unless the first slice is explicitly small and verifiable
- If a slice is implemented, existing checks pass and browser comparison proof exists for old versus new route behavior
- The final review artifact names what remains out of scope
Failure modes
- Mistake: turning a migration map into a giant unreviewed rewrite. Mitigation: require a first safe slice and stop for review if the change is not small and verifiable.
- Mistake: packing the entire repo without topic discipline. Mitigation: preview with a migration-specific search phrase and narrow before writing the bundle.
- Mistake: treating Oracle's output as fresh repo truth after code changes. Mitigation: once implementation begins, inspect current files locally and verify against the running app.
- Mistake: using browser proof too early. Mitigation: use browser proof after a concrete UI slice exists; use the Oracle plan and receipt as planning proof before edits.
Agent references
Oracle codebase handoff prompt - Use this as the copy-paste workflow shape for PackX preview, PackX bundle creation, Oracle browser handoff, returned-plan file, and local verification loop.workshop-followup/toolkit/prompts/01-oracle-codebase-handoff-prompt.md
Oracle codebase handoff Codex skill - Use this when the local agent needs the strict runnable version: preview first, slug rules, prompt prefix, `--write-output`, `--file`, and plan -> implement -> verify.workshop-followup/toolkit/codex-skills/oracle-codebase-handoff/SKILL.md
Verified Oracle + PackX command surface - Use this to avoid inventing flags. It includes the verified `oracle --engine browser --browser-thinking-time extended` command, `ORACLE_MAX_FILE_SIZE_BYTES`, PackX preview/write commands, token-limit notes, and slug rules.workshop-followup/toolkit/bundles/code-oracle-packx.md
Lesson 01 validated references - Use this as the taught-source boundary for the Oracle topic: Codex-to-browser quota offloading, ChatGPT Pro Extended as a high-context browser surface, PackX context bundling, MCP/browser bridge, low concurrency, and plan -> implement -> verify.workshop-followup/oracle/01-references.json
PackX preview command - Run before writing any bundle so the agent can check matched files and token estimate instead of blindly sending irrelevant context.packx --preview -s "<TOPIC>"
PackX bundle command - Write the relevant codebase context into a model-readable markdown file that Oracle can attach.packx -s "<TOPIC>" -f markdown --no-interactive -o .notes/handoff-bundle.md
Oracle browser handoff command - Send the PackX bundle to browser ChatGPT with extended thinking and save only the final assistant message to a local plan file.ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[<3-5-word-kebab-slug>]\n\n<the big analysis question>" --slug "<3-5-word-kebab-slug>" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md
CMUX browser/local verification surface - Use a browser pane or browser-agent-style workflow to prove web app behavior after local implementation, especially login, checkout, navigation, and route migration flows.cmux --json tree; cmux read-screen; local dev server URL from repo package scripts
Implementation notes
- Use Oracle only for read-heavy, large-codebase analysis. Small local edits should stay in Codex without the browser handoff.
- Always preview PackX output before writing `.notes/handoff-bundle.md`; the preview is the quality gate for scope and token cost.
- The Oracle slug must be 3-5 kebab words, and the prompt must start with `[same-slug]`, then a blank line, then the question.
- Keep browser concurrency low: no more than two or three Oracle browser requests at once.
- Treat `.notes/oracle-plan.md` as a planning artifact, not a commandment. The local agent still has to inspect current files, implement the smallest safe slice, and verify with tests/build/browser proof.
- Keep `.notes/` artifacts local working files. Do not commit Oracle bundles or plans unless the repo deliberately wants them.
- For browser proof, prefer user-visible receipts: screenshot, accessibility snapshot, console-free run, route/path evaluation, or a short transcript of click/fill/evaluate steps.
- Do not put secrets, customer data, real payment credentials, or private cookies into PackX bundles, logs, browser screenshots, or `.notes/` receipts.