Dependency Upgrade

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).

1. 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.

1. 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.

1. **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).

1. Produce a rollback plan — the exact commands to revert this specific

bump (e.g. git revert , 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:   -> 
Changelog/migration notes reviewed: 
Gate before bump: 
Gate after bump: 
Migrations applied: 
Gate after migration: 
Rollback plan: 

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pinexai
• Source: pinexai/claude-code-skills
• License: MIT

Install and usage instructions live in the source repository linked above.