Dependency Upgrade

When this fires

Upgrades are usually done ad hoc: bump the version, see what breaks, patch around it. That works until a major-version jump silently changes behavior that isn't caught by whatever happened to be run afterward, or until a multi-package bump makes it impossible to tell which bump broke what. This skill locks the upgrade into a bounded, gated, reversible sequence.

Protocol

1. Read the changelog / migration notes for the exact version delta before touching anything — not a summary from memory, the actual changelog or migration guide for the specific version jump being made (current version → target version).
2. Bump one package at a time. Even if multiple packages need upgrading, each gets its own bump-gate-commit cycle. Never bundle unrelated package bumps into a single step — it destroys the ability to attribute a failure to a specific change.
3. Run the test gate after each bump, before making any other change. The gate is whatever the project already uses to verify correctness (test suite, build, typecheck) — run it, don't assume it would pass.
4. On gate failure, apply only the migrations documented in step 1's changelog/migration guide, then re-run the gate. Do not improvise fixes for breaking changes that aren't in the documented migration path — if the failure isn't explained by the documented changes, stop and investigate before proceeding (it may not be a migration issue at all).
5. Produce a rollback plan — the exact commands to revert this specific bump (e.g. git revert <sha>, or the exact prior version pin) — before considering the upgrade finished, whether or not anything went wrong.

Hard rules

• Never bump more than one major version in a single step (e.g. v2 → v4 must go through v3 first, or be explicitly called out as a deliberate skip with its own migration research, never assumed safe).
• Never skip the test gate, even for a patch/minor bump that "should" be safe — that assumption is exactly what this skill exists to not make.
• Always leave a rollback path stated in exact, runnable commands, not "you could probably just revert this."
• Migrations applied must trace back to the documented changelog/migration guide read in step 1 — don't guess at what a breaking change wants.

Output

Per package bumped:

Package: <name> <old version> -> <new version>
Changelog/migration notes reviewed: <link or source>
Gate before bump: <pass/fail — baseline>
Gate after bump: <pass/fail>
Migrations applied: <none, or the specific documented changes made>
Gate after migration: <pass/fail>
Rollback plan: <exact command(s) to revert this bump>