---
name: jayrha/dependency-upgrader
source: https://app.decimal.ai/s/jayrha-dependency-upgrader@1/SKILL.md
source_sha256: 835d8b5f96fd
---

# Dependency Upgrader

## Overview

This skill drives safe, auditable dependency upgrades across ecosystems
(npm/yarn/pnpm, pip/poetry/uv, cargo, go modules, bundler, maven/gradle,
composer). The core discipline: **one upgrade per commit, tests green between
each, and a known-good rollback point at all times**. Never bulk-upgrade
everything and hope.

Keywords: dependency upgrade, bump packages, outdated, semver, breaking change,
changelog, migration guide, lockfile, CVE, security advisory, Dependabot,
Renovate, rollback, npm audit, pip-audit.

Use this skill when the user wants to update libraries, patch a vulnerability,
migrate a major version, or vet an automated bump PR.

## Core Principles

1. **Isolate.** One package (or one tightly-coupled group) per commit. A failed
   upgrade must be revertable without touching unrelated work.
2. **Read before you write.** Always inspect the changelog / release notes /
   migration guide before bumping across a major version.
3. **Tiered risk.** Patch < minor < major. Batch low-risk; isolate high-risk.
4. **Test gate.** The test suite (or a defined verification command) must pass
   before each commit. No green, no commit.
5. **Always have a rollback.** Know the exact git SHA and lockfile state to
   return to. See `references/rollback.md`.

## Workflow

Follow these steps in order. Do not skip the inventory or the changelog read.

### 1. Establish a clean baseline
- Confirm the working tree is clean (`git status`). If not, stop and ask the
  user how to proceed — never upgrade on top of uncommitted changes.
- Record the current commit SHA as the rollback anchor.
- Run the test suite once to confirm it is **green before** you start. If tests
  are already failing, report that and stop — you cannot attribute later
  failures otherwise.
- Identify the ecosystem and the verification command. See
  `references/ecosystems.md` for the canonical commands per package manager.

### 2. Inventory outdated dependencies
- Run the detector script: `python3 scripts/check_outdated.py --dir <repo>`.
  It auto-detects the ecosystem and prints a risk-tiered table (patch / minor /
  major) plus any known advisories it can surface from the native auditor.
- Or run the native tool directly (`npm outdated`, `pip list --outdated`,
  `cargo outdated`, `go list -m -u all`) — see `references/ecosystems.md`.
- Classify each candidate by semver jump and by whether it is a direct or
  transitive dependency.

### 3. Plan the upgrade order
- **Security first.** Any package with a CVE/advisory jumps to the front.
- Group: (a) safe batch = all patch + most minor of well-behaved libs;
  (b) isolated = every major bump, every framework/build-tool, anything with a
  published breaking-change list.
- Order isolated upgrades so that foundational packages (type systems, build
  tools, test frameworks) go first, then their dependents.
- Present the plan to the user before executing if there is more than one major
  bump or any framework migration.

### 4. Execute — patch & safe minor batch
- Apply the batch (e.g. `npm update`, or pin the resolved versions in the
  manifest), regenerate the lockfile.
- Run the verification command. If green: commit with a clear message
  (see template below). If red: bisect by splitting the batch in half, or fall
  back to upgrading each package individually to find the culprit.

### 5. Execute — major bumps, one at a time
For each isolated upgrade:
1. Read the changelog / release notes / migration guide. Use `WebFetch` or
   `WebSearch` for the project's CHANGELOG and "migration guide vX". Note every
   breaking change that touches the codebase.
2. Bump the single package, regenerate the lockfile.
3. Apply required code changes for the breaking changes you found
   (renamed APIs, removed options, config schema changes, peer-dep bumps).
4. Run the verification command.
   - **Green** → commit (one package per commit). Move on.
   - **Red** → fix forward only if the cause is clear and small. Otherwise
     **roll back this single upgrade** (see `references/rollback.md`) and report
     the blocker to the user with the changelog evidence. Do not leave the tree
     broken.

### 6. Final verification & report
- Run the full test suite (and a build, and a smoke run if applicable) one more
  time on the final state.
- Re-run the auditor to confirm advisories are resolved.
- Summarize: what was upgraded (old → new), what code changed, what was
  deferred and why, and the rollback SHA. Use `templates/upgrade-report.md`.

## Risk Tiers (decision framework)

| Semver jump | Default action | Gate |
|-------------|----------------|------|
| Patch `x.y.Z` | Batch | Tests green |
| Minor `x.Y.z` (well-behaved lib) | Batch | Tests green |
| Minor with deprecation notices | Isolate | Read changelog, tests green |
| Major `X.y.z` | Isolate, one commit | Read migration guide, code changes, tests green |
| Build tool / framework / test runner | Isolate, extra scrutiny | Migration guide + full build + smoke test |
| `0.y.z` libraries | Treat minor as major (0ver) | Read changelog |
| Has CVE/advisory | Front of queue, isolate | Verify advisory resolved post-upgrade |

See `references/breaking-changes.md` for ecosystem-specific breaking-change
patterns (peer deps, ESM/CJS, Python type stubs, Rust edition bumps, etc.).

## Commit message template

```
chore(deps): upgrade <package> from <old> to <new>

- <breaking change handled> / <reason>
- Changelog: <url>
- Resolves: <CVE-id or advisory>   # if applicable

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
```

## Best Practices
- Commit the lockfile in the same commit as the manifest change — never split.
- Keep manifest version ranges intentional; don't silently widen `^` to `*`.
- For monorepos, upgrade a package in one workspace, verify, then propagate.
- When a CVE has no fixed version yet, document the mitigation and the tracking
  issue rather than forcing an incompatible bump.
- Prefer the project's own scripts (`npm test`, `make test`) over guessing.
- If a Dependabot/Renovate PR exists, verify it: read the diff, run tests
  locally, check the changelog — don't merge on green CI alone for majors.

## Common Pitfalls
- **Bulk upgrading then having an opaque red suite** — you can't attribute the
  failure. Always isolate majors.
- **Skipping the changelog** and discovering a removed API at runtime, not
  build time.
- **Forgetting transitive/peer deps** — a major bump often demands its peers
  move too; the lockfile resolution may silently downgrade something.
- **Leaving the tree broken on a failed major** instead of rolling back.
- **Ignoring `0.x` semver semantics** — minor bumps there are breaking.
- **Regenerating the lockfile with a different package-manager version**,
  causing huge unintended churn. Pin the PM version.
- **Upgrading on a dirty tree**, making rollback ambiguous.

## Bundled files
- `references/ecosystems.md` — per-ecosystem commands: detect outdated, audit,
  upgrade, regenerate lockfile, run tests.
- `references/breaking-changes.md` — common breaking-change patterns and how to
  detect/handle them per ecosystem.
- `references/rollback.md` — precise rollback procedures (single upgrade, whole
  batch, lockfile-only) using git.
- `scripts/check_outdated.py` — auto-detecting outdated-dependency reporter with
  risk tiers; pure stdlib, shells out to native tools.
- `templates/upgrade-report.md` — fill-in final report.
- `examples/npm-major-upgrade.md` — worked example: a React major bump.