Verified against Claude Code · 2026-08-03
Turn a major dependency upgrade into a migration plan instead of a live-fire drill
A pre-upgrade prompt that makes Claude Code map every breaking change in the release notes to its actual usage sites in your repo before touching the lockfile, so silent behavior changes get caught, not just the ones that throw a compile error.
The prompt
Ready to copy — highlighted parts are example details you can swap.
You are planning an upgrade of React from 18.2.0 to 19.1.0. Do not modify the lockfile, package manifest, or any application code yet. This is a research and mapping pass first. CRITICAL PATHS — must not regress The checkout form and its validation must not regress — this is the highest-traffic, highest-revenue-risk part of the app. PROCESS 1. Find and read the official changelog, release notes, or migration guide covering every version between 18.2.0 and 19.1.0, not just the final target version — breaking changes in an intermediate minor version are still breaking changes. 2. List every breaking change, deprecation, and default-behavior change you find, in plain language, each with the version it landed in. 3. For each item from step 2, search this codebase for every usage site that touches the changed API, prop, config key, or behavior — cite exact files and line numbers, do not estimate. 4. Classify every usage site as one of: SAFE (unaffected in practice), NEEDS CHANGE (will break or behave differently), or UNCERTAIN (you cannot tell from static reading alone and it needs a test run to confirm). 5. Pay specific attention to changes that alter a default value or silent behavior rather than removing or renaming something — those are the ones that will not throw an error or fail a type check, and are the ones a live-fire upgrade-and-fix-what-breaks approach reliably misses. 6. Propose a staged plan: what to upgrade first if the path isn't a single jump, whether an official codemod exists and should be run before manual fixes, and in what order the NEEDS CHANGE sites should be addressed so each stage is independently testable. OUTPUT A table of breaking change, usage sites, classification, and planned action. Then the staged plan as a numbered list. End with your confidence level in the completeness of this mapping and what would make you more confident, such as running the test suite against the new version in a branch before touching main code. Do not begin making changes until I approve this plan.
Customize the highlighted detailsoptional — the prompt above already works
Why this works
The default failure mode for upgrade X to Y is a live-fire approach: bump the version, run the build or type checker, and fix whatever complains, iterating until it's green — which works fine for changes that throw, but is structurally blind to changes that don't, like a default option flipping, a hook's timing shifting, or a prop silently being ignored instead of rejected. Forcing the changelog read and the usage-site mapping before any edit converts those silent risks into a named list before the upgrade starts, rather than relying on the test suite to happen to exercise every changed default. The SAFE, NEEDS CHANGE, UNCERTAIN classification specifically creates a category for I don't know without running this, rather than forcing a binary safe-or-not call the model isn't actually in a position to make from static reading alone — an uncertain classification is honest, where a model pressured into a yes-or-no answer will often guess safe for a code path it didn't fully trace. Requiring exact file and line citations rather than a general this affects the router claim exploits the same repo-wide search capability that distinguishes an agentic coding assistant from a chat-only one — Claude Code can actually search the entire codebase for every call site of a changed API, which is the step that makes the difference between a plausible-sounding migration plan and one that is actually complete for this specific repo.
What you get back
Breaking change → usage sites → classification (excerpt): - useEffect cleanup timing changed (React 19.0) → hooks/useSocketConnection.ts:34 → NEEDS CHANGE, cleanup now fires before the next effect runs in an edge case this hook relies on the old ordering for. - Legacy Context API fully removed (deprecated since 16, removed 19.0) → zero usages found via search → SAFE. - forwardRef no longer required for function components accepting ref (19.0) → components/ui/Input.tsx:1, Button.tsx:1 → SAFE to simplify, not required. Staged plan: 1) upgrade to 18.3 first to surface deprecation warnings early; 2) run React's official codemod for removed APIs; 3) fix useSocketConnection.ts's cleanup ordering manually, since no codemod covers it; 4) upgrade to 19.1 and re-run the full suite plus a manual pass on checkout. Confidence: moderate on the hooks-timing change specifically — recommend running the checkout flow's integration tests against a 19.1 branch before merging, since that is the one item classified UNCERTAIN above.
Verified against
Claude Code Sonnet 4.6 · 2026-08-03
Cursor 2.1 · 2026-08-02
Changelog
- 2026-08-03 — Initial publish, verified against Claude Code (Sonnet 4.6) and Cursor 2.1.
Building this for real?
This is a free starting point. If you'd rather have custom software built and running for your business, that's Scult's day job.
EXPLORE CUSTOM SOFTWARE
