absolutelyskilled/absolute-upgrade

Start your first response with the ⬆️ emoji.

Absolute Upgrade

Bring dependencies current — safely, in risk-ranked waves, with tests green after each. Not a blind npm update: outdated and vulnerable deps are grouped by blast radius (patch/minor → safe wave; major/breaking → gated, one at a time, changelog-read), applied incrementally, and verified against the project's own test suite.

Runs the shared engine in references/health-engine.md — read it for the DETECT → SCAN → TRIAGE → FIX → VERIFY → REPORT loop and the safety contract. This file covers only what's specific to dependency upgrades.

---

When to use

• Routine "bring deps up to date" / "upgrade our dependencies".
• A specific bump: "upgrade React to 19", "move off the deprecated X package".
• Clearing npm outdated / Dependabot backlog without 40 separate PRs.

Not for: adding a new dependency (that's a work/feature decision), or auditing vulnerabilities specifically → use /absolute audit (it triages CVEs; upgrade moves versions).

---

What it scans

Per ecosystem, list outdated deps with current → wanted → latest and the jump type:

| Ecosystem | Detect outdated | Lockfile / manifest | |---|---|---| | npm | npm outdated --json | package-lock.json | | pnpm | pnpm outdated --format json | pnpm-lock.yaml | | yarn | yarn outdated --json | yarn.lock | | Python (pip) | pip list --outdated --format=json | requirements*.txt | | Python (poetry/uv) | poetry show --outdated / uv pip list --outdated | pyproject.toml + lock | | Go | go list -u -m -json all | go.mod / go.sum |

Also flag: deps with known deprecations, duplicate/multiple versions of the same package, and direct vs transitive (only direct deps are upgrade targets; transitives follow).

---

Risk ranking (TRIAGE)

Group the upgrade plan into waves by semver jump — safest first:

| Wave | Jump | Default | |---|---|---| | 1 | patch (x.y.Z) | batch together, fix now | | 2 | minor (x.Y.z) | batch by package family, fix now | | 3 | major (X.y.z) / pre-1.0 minor | one at a time, gated — read the changelog/migration guide first, list breaking changes |

For every major bump: locate breaking changes (CHANGELOG, release notes, codemod if the package ships one), inventory call sites that touch the changed API, and state the migration before applying. Peer-dependency conflicts get resolved in the same wave as their driver.

---

Fix & verify

• Apply a wave, regenerate the lockfile, run the project's full test + build (a passing install is not a passing upgrade).
• Majors: apply the version bump and the required code migration in the same wave, or the build breaks. Use the package's codemod where one exists.
• A wave that can't go green within reason → revert it, report it as blocked with the error, keep the green waves. Never --force / --legacy-peer-deps to mask a real conflict.

---

Gotchas

1. Lockfile-only "upgrade". Bumping the manifest without regenerating + committing the lockfile ships untested transitive versions. Always regenerate.
2. Batching a major in with patches. One breaking bump fails the whole wave and hides which change broke it. Majors are always solo.
3. Green install ≠ green project. npm install succeeding proves nothing — run tests.
4. Pinning around a failure. If a bump breaks something, fix or defer it; don't pin the dependency tree to dodge it silently.

---

Companion commands

• /absolute audit — if the goal is fixing vulnerabilities, start there; it'll route back here for the version moves.
• /absolute deflake — flaky tests can mask whether an upgrade truly passed.
• /absolute work — if an upgrade needs real feature-level migration work, hand off.