---
name: dependency-upgrade
description: Safely upgrade a dependency (or batch) with verification. Use for routine + security upgrades.
---

# Skill: Dependency Upgrade

## When to use

Security advisory, scheduled maintenance, or unblocking a needed feature.

## Steps

1. Read the changelog/migration guide for breaking changes.
2. Upgrade in isolation (one package or one cohesive group) — not "upgrade everything".
3. `pnpm install` → `pnpm validate` → `pnpm test` → `dotnet build && dotnet test`.
4. For majors, exercise the actual feature, not just the build.

## Gotchas

- **Node 20.11 here is pinned** — packages requiring Node ≥20.19 (eslint 10, eslint-visitor-keys 5) break install. The root `pnpm.overrides` pins these; check there before bumping eslint/typescript-eslint.
- pnpm `overrides` force transitive versions — update them deliberately, document why.
- .NET uses Central Package Management — bump versions in `dotnet/Directory.Packages.props`, never inline.
- Lockfile changes get committed; review the diff for unexpected transitive bumps.
- Security upgrades: confirm the advisory is actually resolved (`pnpm audit`, `dotnet list package --vulnerable`).

## Validation

Build + tests green; feature exercised for majors; lockfile diff reviewed; advisory resolved.
