Dependency Update Safety

Library Updater — keep dependencies current without breaking the build

A disciplined loop for upgrading dependencies: audit what is behind, read what changed, apply in small reversible batches, test between each batch, and roll back the instant a batch regresses. The build stays green from start to finish.

⚠️ Critical Constraints

• Never bump everything at once. Batch by risk (patch → minor → major, smallest first) and test between batches. Why: a single all-in upgrade that fails gives you no way to know which package broke it, forcing a full revert.
  • WRONG: npm update && npm test (one giant diff, no bisect path)
  • CORRECT: patch batch → test → commit → minor batch → test → commit → ...
• The lockfile is part of the change. Always commit the manifest AND the lockfile together. Why: committing package.json without package-lock.json (or go.mod without go.sum) ships a non-reproducible build that resolves differently on the next machine.
• Read the changelog before a major bump, every time. Why: majors signal breaking changes by convention; upgrading blind turns a 10-minute read into a multi-hour debugging session.
• A clean working tree is the precondition, not a nicety. Refuse to start with uncommitted changes. Why: rollback (git checkout -- <manifest> <lockfile>) is only clean when there is nothing else to lose.
• Pinned-for-a-reason stays pinned. Honor existing version pins / ranges and any // pinned: <reason> comments. Why: a deliberate hold (known regression, peer-dep conflict, license) is institutional memory; silently bumping past it reintroduces a solved problem.

Why This Exists

Dependency drift is silent until it is expensive: security advisories pile up, majors stack so high the eventual upgrade is a rewrite, and "just update everything" upgrades fail with no way to tell which package broke. Agents make this worse by bumping in one shot and declaring victory before tests run. This skill enforces the only safe shape — small batches, evidence between each, clean rollback — so currency never costs the build.

Quick Start

# 1. Detect ecosystem + list what is behind (writes outdated.txt)
bash {baseDir}/scripts/audit-deps.sh > outdated.txt

# 2. (after each batch) verify the build still passes for THIS ecosystem
bash {baseDir}/scripts/run-tests.sh   # exit 0 = green, non-zero = roll back

# 3. self-check this skill
bash {baseDir}/scripts/validate.sh

Workflow

Phase 0 — Preconditions

• Confirm a clean tree: git status --porcelain must be empty. If not, stop and surface it; do not proceed.
• Identify the baseline test command (CI config, Makefile, package.json scripts). Record it; it is the gate for every batch.
• Checkpoint: tree clean AND a known-green test command exists.

Phase 1 — Audit (current vs latest)

• Run scripts/audit-deps.sh to enumerate outdated packages with current → wanted → latest and the jump type (patch / minor / major).
• Note any pins, ranges, or pinned: comments — these are excluded from bumping.
• Checkpoint: outdated.txt lists every candidate with its jump type.

Phase 2 — Plan the batches

• Group candidates into ordered batches: patch, then minor, then each major individually (majors are never batched together).
• For every major, read its changelog / release notes and record the breaking changes and required code edits before touching anything.
• Checkpoint: a written batch plan; every major has a changelog summary.

Phase 3 — Apply + test, one batch at a time

• Apply exactly one batch (update manifest + regenerate lockfile).
• Run the baseline test command via scripts/run-tests.sh.
• Green: commit the manifest + lockfile with a scoped message, then continue.
• Red: roll back this batch only (git checkout -- <manifest> <lockfile> and reinstall), record the failure, and either split the batch finer or skip the offending package. Never carry a red batch forward.
• Checkpoint: after each batch the suite is green and the change is committed.

Phase 4 — Report

• Write dependency-update-report.md: batches applied, packages bumped with before→after versions, packages skipped (with reason), rollbacks, and remaining majors deferred for follow-up.
• Checkpoint: report exists; tree is clean and green.

Output Specification

• Filename: dependency-update-report.md (repo root or a path the caller gives).
• Format: sections — Applied (table: package | from → to | jump | batch), Skipped (package | reason), Rolled back (package | failure), Deferred (majors needing dedicated work). Each applied batch links its commit SHA.

Quality Rubric

• Every applied batch has a corresponding green test run AND a commit — no batch is committed without a passing suite.
• Manifest and lockfile are committed together in every batch (verifiable in git show <sha> --stat).
• Every major version bump cites the changelog section that documents its breaking changes.
• The report accounts for every outdated package: applied, skipped, rolled back, or explicitly deferred — none silently dropped.

Examples

npm, mixed jumps. audit-deps.sh finds 6 outdated: 3 patch, 2 minor, 1 major (react 18→19). Batch 1 (patches) → test green → commit. Batch 2 (minors) → green → commit. Batch 3 (react major): read the v19 migration notes, apply, fix the two breaking call sites, test → green → commit. Report records all three.

Rollback path. A minor batch turns the suite red. Run git checkout -- package.json package-lock.json && npm ci, suite green again. Bisect: re-apply the minor packages one at a time; lodash 4.17.20→4.17.21 is the culprit. Skip it, record "skipped: 4.17.21 breaks ", continue.

Troubleshooting

See Also

• scripts/audit-deps.sh — Execute: lists outdated deps with jump types.
• scripts/run-tests.sh — Execute: runs the ecosystem's test gate; exit code is the verdict.
• scripts/validate.sh — Execute: self-checks this skill's structure and scripts.