Dependency Upgrade

---
name: dependency-upgrade
description: Upgrade dependencies with breaking-change review and verification. Use when asked to update, bump, or migrate packages or framework versions.
---

# Dependency Upgrade

An upgrade is not done when the version number changes — it is done when the app still works.

## Procedure

1. **Inventory.** `npm outdated` (or `pnpm outdated` / `poetry show --outdated`). Record current → target for each package.
2. **Read the release notes for every major bump.** Check CHANGELOG, GitHub releases, and migration guides. List breaking changes that could touch this codebase.
3. **Grep for the breaking APIs** before upgrading: `rg "removedFunctionName"`. If the code uses them, plan the codemod.
4. **Upgrade in stages:**
   - Patch/minor updates in one batch
   - Each major version in its own commit, riskiest package first
   - Never upgrade 10 majors at once
5. **After each stage, run the gates:** install, typecheck, lint, tests, build. All must pass before the next.
6. **Inspect the lockfile diff** (`git diff package-lock.json | head -200`): watch for unexpected transitive major bumps or duplicate versions of the same package.
7. **Check for deprecations** in the output of the test/build run — migrate them now while context is fresh.

## Migration edits

- Follow the official migration guide exactly; do not improvise new APIs.
- Search for every usage site; a missed call site compiles fine and breaks at runtime.
- For config format changes, migrate the config file and verify the tool actually starts.

## Report

- Table: package, old → new, risk level, breaking changes relevant to us
- Validation results (tests/build/lint)
- Residual risks and how to roll back (`git revert` of the stage commit, or pin to previous version)