Imported from entorenee/dotfiles (modules/home/claude/config/skills/dependency-upgrades/SKILL.md). Install upstream with npx skills add entorenee/dotfiles --skill dependency-upgrades. Copyright stays with the author.

Dependency Upgrades

Overview

Systematic, phased approach to npm dependency upgrades with validation gates between each phase. Core principles: one major version bump at a time, and within-major bumps ship as small grouped chunks — never one giant batch — each fully validated and committed before the next. "It's only a patch/minor" is not a safety guarantee (see Within-Major Isn't Automatically Safe).

When to Use

• Upgrading outdated npm dependencies (especially major versions)
• Planning a multi-package upgrade strategy
• Resolving peer dependency conflicts
• An outdated inventory showing multiple major bumps

Not for: Single patch/minor bumps, adding new dependencies, or non-npm ecosystems.

Package manager — detect, don't assume

CLAUDE.md § Project Command Discovery already requires this: read the lockfile at the repo root and use that manager consistently. pnpm-lock.yaml → pnpm, yarn.lock → yarn, bun.lockb → bun, package-lock.json → npm. Never fall back to npm because a command in this file looks like npm.

The rest of this skill is written manager-neutral. Where a step genuinely differs:

yarn and bun follow the same shape — substitute their equivalents.

Never delete the lockfile to resolve a problem, whichever one it is. Reinstall from it.

Workflow

digraph upgrade_flow {
    rankdir=TB;
    node [shape=box];

    scope [label="1. Scope\nDispatch dependency-scoper agent\nReturns JSON: within-major, deferred-majors, coupled"];
    baseline [label="2. Baseline\nPin versions\nVerify zero errors\nCommit clean state"];
    research [label="3. Research\nDispatch migration-researcher agents IN PARALLEL\n(one per deferred major, single Agent block)"];
    phase [label="4. Execute Phase\nOne small grouped chunk\n(within-major group OR\nsmallest major working set)\ncommit per chunk"];
    validate [label="5. Validate\ntsc + lint + test\n(AI runs these)"];
    engineer [label="6. Engineer Gate\nnpm run build\nManual testing\n(MUST NOT skip)"];
    done [label="All phases done?" shape=diamond];
    memory [label="7. Update Memory\nVersions, issues,\nlessons learned"];
    complete [label="Complete"];

    scope -> baseline -> research -> phase -> validate;
    validate -> engineer [label="pass"];
    validate -> phase [label="fail\nfix first"];
    engineer -> done [label="approved"];
    engineer -> phase [label="rejected\nfix issues"];
    done -> memory -> phase [label="no\nnext phase"];
    done -> complete [label="yes"];
    complete -> pr [label="engineer\nasks for PR"];
    pr [label="8. Create PR\nDraft mode ONLY\nWait for engineer\nto request this"];
}

Subagent Orchestration (required)

This skill is parallelizable and must use subagents to keep registry/web chatter out of the main conversation:

• Scoping — dispatch the dependency-scoper agent once. It returns the structured upgrade plan. Do not run outdated inventories or per-package registry-view loops in the main thread.
• Migration research — for each entry in deferredMajors from the scoper output, dispatch a migration-researcher agent. Send them in a single message so they run concurrently. Aggregate the briefs into the phase plan you present to the engineer.

Inline (non-agent) work in the main thread is limited to: presenting plans, editing package.json, running validation (tsc/lint/test), and creating commits/PRs when the engineer asks.

Sandbox notes (do not invent workarounds)

Registry-metadata queries (npm outdated, npm view, npx npm-check-updates, pnpm outdated, pnpm dlx ncu, etc.) are listed in sandbox.excludedCommands and run outside the sandbox. They use the user's real ~/.npm / pnpm caches directly — no --cache /tmp/... flag, no HTTP_PROXY=... prelude, no --registry=... overrides are needed. If one of these commands fails, the failure is the real failure — debug it, don't paper over it with per-command sandbox workarounds.

Installs and mutating commands (npm install, pnpm install, pnpm add, builds, tests) still run inside the sandbox. The NODE_OPTIONS=--dns-result-order=ipv4first env var is already set globally for those.

Quick Reference

Within-Major Updates: Chunk, Don't Batch

The dependency-scoper agent's withinMajor output finds the highest version in each package's current major (the --target minor inventory above) — the most frequent miss when relying on the plain outdated inventory alone. Use it as the inventory, not as a single commit.

Do NOT bundle all withinMajor entries into one giant Phase 1. A patch/minor bump is not automatically safe — batching them buries a single bad bump inside dozens of good ones, forcing an expensive bisect and repeated full reinstalls (churn) to find it. Instead, split withinMajor into small grouped chunks and validate + commit each independently, so blast radius stays small and any breakage is trivially attributable to the chunk that introduced it.

Chunking strategy

Group the withinMajor inventory into commit-sized chunks, roughly:

1. Pure leaf utilities / SDKs (AWS SDK, google-*, axios, dayjs, ioredis, mysql2, svix, contentful, etc.) — lowest risk, can be a larger chunk.
2. Framework-adjacent runtime (next+eslint-config-next, tRPC stack, TanStack, Radix, MUI, stream-*) — one chunk per ecosystem.
3. Type packages (@types/*) — separate chunk; these fracture the type graph (see below).
4. Test/build toolchain (vite, @vitejs/plugin-react, vitest, coverage, eslint tooling) — separate chunk; regressions here mass-fail tests, not prod.
5. Anything the scoper flagged as coupled or transitively pinned — its own chunk.

Present the chunk plan to the engineer and land one chunk per commit. If a chunk needs > ~15 packages, the engineer can opt to combine, but default to smaller.

Within-major isn't automatically safe — failure modes seen in the wild

Validate every chunk with the full gate (tsc + lint + test) before committing. These are real regressions caused by patch/minor bumps:

• Peer-dependency version splits. Bumping a widely-depended type package (e.g. @types/react) to a version transitive deps don't yet resolve to leaves two copies in the tree. That fractures the type graph and silently breaks declare module augmentations (they merge into the wrong copy) → cascades of "property X does not exist" / implicit-any errors far from the bump. Fix: hold the type package at the version the tree already dedupes on, or force a single version.
• Transitive hard-pins. A wrapper package pins an exact version of a shared core as a direct dependency (not a peer) — e.g. a table/UI wrapper pinning its -core. Bumping your direct dep ahead of it creates a duplicate with distinct type identity → augmentations/types break. Fix: keep the shared dep at the version the wrapper pins until the wrapper updates.
• Type-inference perf regressions. A schema/validation library minor bump can balloon tsc memory/time (e.g. a z.object taking tens of seconds each), OOM-ing the typecheck. Diagnose with tsc --generateTrace <dir> + @typescript/analyze-trace <dir> (via npx / pnpm dlx) (hot-spot files/expressions), not by throwing more heap at it. Fix: hold the library back.
• Test-toolchain transform regressions. A vite/@vitejs/plugin-react/vitest patch can change the JSX runtime (automatic → classic) → mass ReferenceError: React is not defined across every render test. Fix: keep the vite+plugin-react+vitest+coverage set on the versions that pass, as a coupled group.

Diagnosing a bad chunk. If a chunk fails validation, don't bisect the whole batch — the chunk is already small. Check for duplicate installs first (find node_modules -type d -name <pkg>, lockfile grep, .pnpm virtual keys), compare resolved versions against the last-good branch, and revert the single offending package (hold it back with a documented reason). Duplicate/split resolutions are the leading cause and are invisible in package.json — they only show in the installed tree.

Validation: Run the Package's OWN Toolchain

After each chunk, run the full gate — tsc, lint, test — on a clean install. In a monorepo/workspace, this must run through the target package's own binary, never the root-hoisted one.

• Run via pnpm --filter <pkg> <script> (or <pkg>/node_modules/.bin/<tool>), matching how CI invokes it. Do not shortcut to <root>/node_modules/.bin/<tool>.
• Why: the root node_modules/.bin hoists whichever version of a multi-version tool won hoisting — often an older one belonging to a sibling package. Running that against your package silently uses the wrong toolchain. Real example: root hoisted vitest@3 / vite@6 / @vitejs/plugin-react@4 (from other workspaces) while the target declared vitest@4 / vite@8; running the root vitest emitted classic JSX and produced 1394 bogus ReferenceError: React is not defined failures — pure harness artifact, zero real breakage.
• Before trusting a mass failure, confirm the runner. A sudden flood of identical, fundamental errors (JSX runtime, module-not-found, "X is not defined" everywhere) is more likely a wrong-binary/duplicate-toolchain artifact than a real regression. Check the resolved tool version (<pkg>/node_modules/.bin/<tool> --version, or the lockfile importer block) against what the package declares.
• Single-version tools hoisted at root (typically tsc/typescript, next) are safe to run from root — but verify the version is single before assuming it.
• Snapshot churn from UI-lib bumps (class-name reordering, icon markup) is expected; confirm the diff is cosmetic, then regenerate with -u. Don't -u blindly — a structural/logic diff hiding among cosmetic ones is a real regression.

Peer Dependency Conflicts

An unmet peer is not cosmetic. A peer range the tree cannot satisfy has produced hard runtime crashes, not warnings — e.g. a native RN cluster where one package's peer wanted webrtc ^145 against a ^137 pin installed cleanly and then threw AbstractMethodError on 100% of Android startups. Read the peerDependencies of the packages you bump; a clean install is not evidence the tree is coherent.

Resolution order of preference:

1. Align versions (upgrade/downgrade to compatible range)
2. Check for newer versions of conflicting packages
3. An override (last resort, document why) — placed where this package manager reads it:
   • pnpm workspace: overrides in pnpm-workspace.yaml. pnpm 10 ignores a pnpm.overrides block in the root package.json — no error, the override simply does nothing. (Verified in a workspace; the single-package case is unconfirmed, so check before relying on it.)
   • npm / yarn: overrides / resolutions in package.json.
4. Consider alternative packages

Migration Research (Before ANY Major Bump)

Dispatch one migration-researcher agent per deferred major from the scoper output. Send them all in a single message so they run concurrently — sequential dispatch defeats the purpose.

Each agent returns a brief covering: risk rating, breaking changes filtered to actual codebase usage, codemods, coupled upgrades, and verification steps. Aggregate these into the phase plan presented to the engineer.

Only do this research inline in the main thread if a single ad-hoc bump is being assessed and dispatching an agent would be overkill.

Memory File for Multi-Session Upgrades

For upgrades spanning multiple sessions, create a progress file in $ARTIFACTS/plans/ tracking: current phase, completed phases with exact versions, validation results, issues/lessons, remaining phases, and next actions. See detailed-guide.md in this skill directory for the full template.

Anti-Patterns

• Batching all within-major (patch/minor) bumps into one commit on the assumption they're safe. They cause version splits, transitive-pin duplicates, perf regressions, and toolchain breaks just like majors — and a mega-batch turns one bad bump into a costly bisect + repeated reinstalls. Chunk and commit incrementally.
• Treating a green package.json as a green tree. Version mismatches live in the installed tree (duplicate copies, split peers), not in package.json. Verify with the full validation gate on a clean install, not by eyeballing declared versions.
• Updating unrelated major packages simultaneously
• Skipping the build (dev success != build success)
• Deleting the lockfile instead of reinstalling from it
• Ignoring peer dependency warnings
• Committing a state that requires --legacy-peer-deps

Communication Protocol

After each phase, report: validation results, packages updated (old -> new), issues encountered, and next phase plan. Always remind the engineer to run the project's build before approving.

Pull Request Creation

NEVER auto-create a PR. Wait for the engineer to explicitly ask you to create one. When asked:

• Always create in draft mode (--draft)
• Use the PR template below

PR Template

## Summary

{1-2 sentence overview: what this PR covers and how it fits into the larger upgrade effort.}

### Within-major chunks ({count} packages across {N} commits)

One row per committed chunk (leaf utils, per-ecosystem, types, test-infra, …):

- **{chunk name} ({count}):** {comma-separated packages, notable jumps called out, e.g. "@aws-sdk/client-s3 (3.629→3.1034)"}

### Major version bumps ({count} packages)

| Package | From | To | Risk | Blast Radius |
|---------|------|----|------|-------------|
| `{package}` | {old} | {new} | {Very Low/Low/Medium} | {N files — brief justification} |

### Held back (with reason)

Packages intentionally NOT bumped this round — record so the next session doesn't retry them blindly:

| Package | Available | Held at | Reason |
|---------|-----------|---------|--------|
| `{package}` | {latest} | {pinned} | {peer split / transitive pin / perf regression / toolchain break / major deferred} |

### Code Changes (beyond package.json)

- **`{file path}`** — {what changed and why}

### Other

- {Deferred upgrades with reasons}
- {Removed unused packages with justification}
- {Notable peer dep resolutions}

## Test plan

- [x] `{typecheck cmd}` — {result}
- [x] `{test cmd}` — {result}
- [x] `{build cmd}` — verified by engineer
- [ ] Verify dev server starts cleanly
- [ ] Smoke test critical paths (auth, navigation, data tables)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Key Principles

• Risk column: Rate each major bump (Very Low / Low / Medium) based on blast radius and API surface change
• Blast radius: State file count and why it's safe (e.g., "1 file — dev dep for test data only", "0 files — CLI-only usage")
• Deferred section: Document what was intentionally skipped and why (peer dep blockers, resolution conflicts, risk too high for this batch)
• Code changes section: Only list changes beyond package.json/lock — import path fixes, API adaptations, test updates, snapshot refreshes

Full Reference

See detailed-guide.md in this skill directory for complete phase-by-phase instructions, memory file templates, responsibility matrix, recovery procedures, and common issues reference.