Dependency Upgrade Skill

---
name: dependency-upgrade
description: Upgrade a dependency or framework version safely. Use when the user asks to upgrade, bump, or migrate a package, resolve a security advisory, or when a major version is involved.
---

# Dependency Upgrade

The dangerous part of an upgrade is never the compile errors. It is the behavior that changed quietly, passed the build, and failed on real data days later.

## Establish the ground truth

1. The exact current and target versions, from the lockfile rather than the manifest range.
2. Why we are upgrading: a security fix, a needed feature, end of support, or routine currency. This decides how much risk is acceptable and whether an intermediate version is a better target.
3. Every place the package is used. Grep for the import, and also for its transitive interfaces: types, plugins, peer dependencies, and config keys.
4. What tests cover that code. Write the missing ones before starting. They are the only thing that will tell you the upgrade worked.

## Read the changelog against your own code

Fetch the actual migration guide and release notes for every version between current and target, including the intermediate majors. Do not work from memory: version-specific breaking changes are precisely what recalled knowledge gets wrong, and a confident wrong answer here costs a day.

Produce two lists:

**Affects us**: each breaking change matched to the specific code that uses it, with what has to change. This filtered list is the plan.

**Silent changes**: behavior differences that will not produce an error. Changed defaults, stricter validation, different error types, altered ordering or timing, deprecation that now warns or now removes. For each, name how to check it. These cause the incidents.

## Stage the work

Break it into stages that each end in a shippable state, and prefer several small merges to one long-lived branch. For each stage: what changes, what to verify, and how to roll back.

Apply official codemods where they exist, then read the diff they produced. A codemod is a starting point, not a result.

## Verify

After each stage: typecheck, the tests covering the changed code, then the full suite, then the checks that tests do not cover. Exercise the actual runtime path, since a package that resolves and compiles can still fail on first use.

After deploy: name the metrics and error signatures to watch, and for how long. Most upgrade regressions appear under real data and real concurrency, not in CI.

## Rules

- Never upgrade several major versions in one change. Each one separately, verified, merged.
- Never suppress a new warning to make the build clean. The warning is the upgrade telling you something.
- If tests fail after the upgrade, understand why before changing them. A test updated to match new behavior is either a correct migration or a silently accepted regression, and only reading it tells you which.
- Decide the abort criteria before starting, not at the point where reverting has become expensive.

## Report

Versions moved, breaking changes handled, silent changes checked and how, what could not be verified, and what to watch in production.