# Breaking-Change Triage

Use this reference when classifying specific breaking changes from an official migration guide into blocking vs. cosmetic buckets, and when mapping each change to the code paths it actually touches.

> Version note: breaking-change lists are per-release and change across minor/patch versions within a major too (e.g. deprecation warnings added in a `.1` release ahead of removal in the next major). Re-pull the current official migration guide for the exact source and target versions before triaging — do not reuse a prior session's list without re-verifying it still matches.

## What people get wrong

The naive assumption is:

> "The migration guide lists N breaking changes, so there are N things to fix, roughly equal effort each."

Wrong. Migration guides mix at least three fundamentally different categories of severity, and treating them as equivalent produces either false alarm (blocking a low-risk upgrade over a warning) or false confidence (shipping an upgrade that silently changes runtime behavior).

## The three-tier classification

### 1. Build-blocking

The code will not compile or the build will fail outright. These are the safest category paradoxically — the build tells you immediately, and CI catches them before merge.

Examples grounded in official docs:
- React 19 removing `propTypes`/`defaultProps` on function components — this is a type/lint-level break in TypeScript codebases, not always a hard compile failure in plain JS, so verify whether the project uses TypeScript strict mode or just runtime PropTypes checks before calling it "build-blocking" vs. "silently degraded."
- Any removed export, removed CLI flag, or removed config key — grep the repo for the literal symbol/flag name to confirm actual usage before flagging it as in-scope; do not flag "this symbol was removed" as risk if the repo never imports it.

### 2. Runtime-blocking (behavioral break, not compile break)

The code compiles and builds fine, but behaves differently or throws at runtime. These are more dangerous than build-blocking changes because CI without adequate integration/e2e coverage will not catch them before production.

Grounded example: Next.js 15 making `cookies()`, `headers()`, `draftMode()`, and `params`/`searchParams` asynchronous. Old synchronous call sites do not necessarily fail to build in JS (they may still "work" until the returned Promise is used incorrectly) — they fail or misbehave at runtime, and the failure mode may only surface on paths exercised by real traffic, not by every test.

Grounded example: Next.js 15 changing `fetch` to be uncached by default. This produces no build error and no runtime crash — it produces a silent regression in data freshness or, more dangerously, in cache-hit-dependent performance/cost assumptions. This class of change is the one triage must not under-weight, because there is no error to signal it happened.

For every runtime-blocking change, identify:
- the specific API/behavior that changed (cite the migration guide section),
- whether an automated codemod exists and is officially named for it (do not assume — check `references/dependency-compatibility-matrix.md`-adjacent codemod listings in the framework's own upgrade docs),
- what test coverage (if any) would actually exercise the changed code path — if none, say so explicitly as a residual risk, not a solved problem.

### 3. Cosmetic deprecation

The code still works exactly as before; the framework emits a warning (console warning, lint warning, or doc note) that the API is scheduled for removal in a *future* major, not this one.

Do not present these as this-upgrade risk. List them separately as "deprecation debt to schedule before the *next* major," since conflating them with real blockers dilutes attention from what actually needs fixing before merge.

## Mapping to blast radius

For every build-blocking and runtime-blocking item (never cosmetic-only items, to keep the list actionable):

1. Identify the literal API/symbol/config key changed.
2. Search the repo (`Grep`) for actual usage of that symbol — imports, JSX usage, config keys, CLI invocations in `package.json` scripts.
3. Count distinct files/modules touched; do not estimate — enumerate.
4. Flag any usage inside test fixtures or mocks separately from production source, since test-only usage changes the risk profile (breaks CI, not production).
5. If the symbol is re-exported or wrapped by an internal abstraction layer, note that fixing the wrapper once may resolve many call sites — do not multiply file count by naive per-callsite fix cost.

## When to push back

Push back if the user asks you to://"just estimate the risk without checking the actual official migration guide for this version" — a risk assessment built from memory of a different major version (or a different framework entirely) is not a risk assessment, it is a guess wearing a risk assessment's clothes.
Push back if the user wants to skip the blast-radius search step because "it's probably fine" — "probably fine" is exactly the failure mode this skill exists to replace with an enumerated count.
Push back if the user wants to bundle a same-framework major upgrade together with unrelated dependency upgrades in one PR — that makes the blast radius of a failure ambiguous (which upgrade caused the regression?) and should be flagged as a review/rollback risk, not silently accepted.

# Dependency Compatibility Matrix

Use this reference when the actual upgrade blocker is a third-party dependency's peer-dependency constraint, not a breaking change in the core framework itself.

## What people get wrong

The naive assumption is:

> "The framework's own migration guide says the upgrade is straightforward, so the upgrade is straightforward."

Wrong. The framework's own breaking-change list only covers the framework. It says nothing about whether the state-management library, UI component library, testing library, or build plugin the project actually depends on has published a compatible release yet. A framework-major upgrade is frequently blocked not by the framework's own breaking changes but by an ecosystem library that has not shipped peer-dependency support for the new major, sometimes for months after the framework's release.

## The actual compatibility surface

For a same-framework major upgrade, the dependencies most likely to gate the upgrade are:

- **UI component libraries** built directly against the framework's internals (not just its public API) — these are the most common blockers because internal API changes (e.g. React's internal fiber/reconciler changes, Angular's internal change-detection changes) can break a component library even when the library's *usage* of the public API looks unchanged.
- **State-management libraries** with framework-version-pinned peer dependencies.
- **Testing-library integrations** (React Testing Library, Angular TestBed harnesses, Vue Test Utils) — these often require a matching major version to support new rendering/hydration internals, and a stale version can produce misleading green tests that do not reflect real runtime behavior.
- **Build-tool plugins/loaders** that wrap the framework's compiler (e.g. a bundler plugin implementing framework-specific fast-refresh or SSR transforms) — these must track framework-internal changes closely and are a common source of "works with `next dev` but breaks under the plugin" issues.
- **Meta-framework version coupling** — e.g. Next.js major versions are coupled to a specific React major/minor floor; do not assess a Next.js upgrade's React compatibility from memory, check the specific Next.js major's stated React peer-dependency range in its own official docs for that release.

## Procedure

1. Enumerate the project's direct dependencies with the framework's own package as a peer dependency (read `package.json` `peerDependencies` fields of the top N most framework-coupled packages actually installed, not a generic list).
2. For each, check whether a release compatible with the target framework major has shipped. Prefer checking the dependency's own official changelog/release notes over inferring from its semver range, since a library may have shipped a compatible peer-dependency range before actually fixing all the runtime breakage that range implies is safe.
3. If a dependency has *not* shipped compatible support, this is a hard blocker independent of how clean the framework's own breaking-change list is — say so explicitly and do not let a clean framework migration guide imply a clean overall upgrade.
4. If a dependency requires a beta/RC release to get compatibility, flag that as an elevated-risk path (pinning to a pre-release for a production dependency) rather than presenting it as equivalent to a stable compatible release.
5. Distinguish "peer-dependency range technically allows the new major" from "the maintainer has stated they tested against the new major" — a permissive semver range is not evidence of compatibility, it is often just an unmaintained range that was never tightened.

## When to push back

Push back if the user wants to force-install (`--legacy-peer-deps` / `--force`) past a peer-dependency conflict as the resolution rather than as a temporary unblock — that suppresses the signal that a real incompatibility may exist and should be logged as residual risk, not treated as "resolved."

Push back if the user assumes a component library "probably still works" because it hasn't announced incompatibility — the absence of an announcement is not evidence of compatibility, especially for internal-API-coupled libraries; recommend an actual smoke test of the specific components in use.

Push back if the plan is to upgrade the framework and defer checking ecosystem-dependency compatibility until after merge — for framework-internal-coupled dependencies (UI kits, test harnesses, build plugins) this ordering inverts the actual risk: the framework's own official migration guide is usually the well-tested, well-documented part, while third-party catch-up compatibility is the least-documented and most likely source of surprise regressions.