Give AI the installed version, target version, official release notes, relevant manifests, lockfile evidence, and test commands. Ask it to produce a plan before a patch. Upgrade one risk boundary at a time, keep unrelated refactors out, and make rollback an explicit part of done.
Why Package Upgrades Are Evidence Problems
A dependency upgrade is not simply changing one number in a manifest. The declared range may differ from the version in the lockfile. A direct dependency can move several transitive packages. A new major version may rename configuration, remove an API, change defaults, require a newer runtime, or alter generated output without producing a compile error.
AI is useful because it can search a repository for imports, configuration keys, adapters, mocks, and assumptions tied to the package. The dangerous part is letting it fill missing facts from memory. A confident migration plan based on the wrong release, the wrong package manager, or an outdated API is still the wrong plan.
Treat the repository and official upgrade documentation as evidence. Treat the model as an analyst of that evidence. If a claim cannot be traced to the lockfile, source code, test output, or supplied documentation, it belongs in an assumptions list — not in the implementation plan.
The Five-Step Upgrade Plan
Record the package name, currently resolved version, requested target, package manager, runtime version, and workspace location. Inspect both the manifest and lockfile. If several applications share the dependency, list them separately; they may have different build pipelines, plugins, or runtime constraints.
Collect the official release notes and migration guide for every version crossed. Ask AI to turn only that supplied material into a ledger with four columns: change, repository evidence, required action, and verification. Any item that lacks repository evidence should be marked not observed, not silently converted into work.
Search for imports, initialization code, configuration, environment variables, wrapper modules, type augmentations, test doubles, fixtures, build plugins, and CI references. Also check generated files and deployment images. The goal is a bounded change map: what must change, what might change, and what is explicitly out of scope.
Keep the package bump and required compatibility edits in one reviewable change. Do not mix in formatting, renamed abstractions, broad refactors, or opportunistic dependency bumps. A focused diff makes failures easier to attribute and rollback easier to execute. If cleanup is valuable, queue it as a follow-up after the upgrade is proven.
Write down the install command, static checks, targeted tests, full regression suite, build command, and any manual behavior to verify. Then define rollback: the commit to revert, the lockfile state to restore, and any data or configuration change that is not automatically reversible. Do this before touching the manifest.
What the Finished Plan Should Contain
Before AI edits code, its output should be specific enough that another developer can challenge it. A useful plan includes:
- Version evidence: current resolved version, target version, runtime requirements, and source links or pasted documentation.
- Affected files: each file or subsystem with the reason it is in scope.
- Required changes: only changes supported by the release notes and repository evidence.
- Unknowns: compatibility claims, plugins, or runtime behavior that still need verification.
- Execution order: package update, compatibility edits, generated artifacts, tests, build, and manual checks.
- Stop conditions: unexpected transitive churn, an undocumented API change, runtime incompatibility, or failing tests that cannot be attributed.
- Rollback: exactly how to return the code, lockfile, configuration, and deployed system to the previous state.
Delete the package name from the plan and read it again. If the plan still sounds correct, it is probably too generic. A real upgrade plan names concrete versions, files, APIs, checks, and failure signals.
Copy-Paste Prompt: Dependency Upgrade Analysis
"Plan this dependency upgrade before changing any files. Package: [name]. Current resolved version: [version]. Target version: [version]. Package manager and runtime: [details]. Official release notes or migration guide: [paste or link the reviewed text]. First inspect the manifest, lockfile, imports, configuration, wrappers, tests, build files, and CI references. Output: (1) verified version delta, (2) breaking-change ledger tied to supplied documentation, (3) affected files with repository evidence, (4) ordered implementation steps, (5) exact verification commands and manual checks, (6) rollback steps, and (7) unresolved assumptions. Do not infer release facts that are absent from the supplied sources. Do not edit code yet."
Review the plan, resolve its unknowns, and only then ask for the smallest implementation step. After each step, inspect the diff and run the corresponding check. If the resolved dependency tree changes more than expected, stop and explain the additional movement before continuing.
Common Failure Modes
The first is asking, "Upgrade this package to the latest version." That leaves the target, source of truth, scope, and success criteria undefined. The second is trusting a green compile as proof; configuration and runtime behavior can change without type errors. The third is accepting a regenerated lockfile without reviewing how much of the dependency graph moved. The fourth is combining the upgrade with a cleanup that makes rollback expensive.
The fix is not a longer prompt by itself. It is a workflow that makes evidence visible: pin the delta, supply the documentation, map usage, isolate the diff, run proportional checks, and preserve a reversible path.
Conclusion
AI can make dependency upgrades faster by finding call sites, comparing documented changes with repository usage, and turning the result into a testable sequence. It becomes risky when it is asked to remember what changed or guess what compatibility means. Keep facts outside the model, keep the diff narrow, and require proof before merge.
Pair this with The AI Change Budget, AI Regression Test Plan Template, AI Merge Readiness Checklist, and The AI Decision Log.