upgrade-breaking-change-navigator

Upgrade Breaking Change Navigator

Source mapping: Tier 3 specialized skill derived from Kotlin_Spring_Developer_Pipeline.md (SK-22).

Mission

Turn a risky platform upgrade into a controlled sequence of small, verifiable moves. Optimize for incremental confidence, not for a single giant leap that hides the source of breakage.

Read First

• Current Gradle wrapper, Kotlin plugin, Spring Boot plugin, JDK, and key dependency versions.
• Version catalogs, convention plugins, and BOM ownership.
• Build failures, test failures, runtime startup failures, and deprecation reports.
• The actual libraries and features in use: Security, Data JPA, WebFlux, AOT/native, messaging, serialization, cloud config.
• Official upgrade notes when available.

Upgrade Strategy

1. Identify the target version and the last known good current version.
2. Identify mandatory intermediate steps. Do not skip major lines casually.
3. Separate upgrade layers:
   • JDK
   • Gradle wrapper
   • Kotlin plugin and compiler
   • Spring Boot and Spring Framework
   • ecosystem libraries
4. Upgrade one authority at a time whenever possible.
5. After each step, verify:
   • dependency resolution
   • compile
   • tests
   • startup smoke
6. Record breakages by layer so the root cause stays attributable.

Advanced Upgrade Hotspots

• javax.* to jakarta.* is both source migration and dependency compatibility migration.
• Spring Security DSL and filter-chain defaults change across major lines. "Compiles" does not mean "same auth behavior."
• Hibernate upgrades can change SQL generation, lazy-loading behavior, sequence handling, and schema expectations.
• Kotlin compiler upgrades can affect KAPT, KSP, compiler plugins, nullability inference, and generated bytecode shape.
• Boot upgrades can change auto-configuration defaults, logging behavior, observability integration, and actuator exposure.
• Native image or AOT support raises a different class of breakages around reflection, proxies, and configuration hints.
• Testcontainers, MockK, bytecode instrumentation, and coverage tooling often lag core platform upgrades.
• JSpecify or other nullability enhancements in upstream libraries may force new Kotlin compile warnings or source changes.

Runtime And Tooling Nuances

• JDK upgrades can tighten module encapsulation, change TLS defaults, alter DNS or timezone behavior, and surface illegal reflective access only in production-like environments.
• Path-matching, error rendering, and Problem Details defaults can shift behavior at the web boundary even when controller code remains unchanged.
• Observability migrations can change metric names, trace propagation, or log correlation behavior, breaking dashboards before the app "breaks."
• Security upgrades frequently change defaults toward stricter behavior. A newly failing request may indicate a safer default, not a broken framework.
• Gradle upgrades can invalidate custom build logic, remote cache assumptions, and plugin internals long before the application code notices.
• Native-image or AOT-capable builds often need separate verification gates because JVM startup passing does not imply native correctness.

Expert Heuristics

• Upgrade the path that gives the highest diagnostic signal first, not merely the path that feels most foundational.
• Upgrade the toolchain that constrains others first only when compatibility docs support that order; otherwise preserve the currently supported matrix as long as possible.
• Let the platform BOM regain control of library families before trying to patch every individual dependency.
• Treat deprecation warnings as migration guidance, not cosmetic noise, when they are in code paths touched by the upgrade.
• If dashboards, alerts, or client contracts are version-sensitive, treat them as part of the upgrade scope, not post-upgrade cleanup.
• If a library is not upgrade-ready, decide whether to pin temporarily, replace it, or postpone the platform target. Do not pretend all paths are equal.
• Maintain a migration log per step: version change, observed failures, compensating fixes, and remaining known risks. This prevents rediscovery loops.
• Prefer canary or staged deployment for behavior-changing upgrades even when compile and test phases are green.
• Preserve a rollback path for deployable upgrades. A technically correct upgrade without operational reversibility is incomplete.

Output Contract

Return these sections:

• Current state: the versions and high-risk features in use.
• Upgrade path: the ordered sequence of upgrades.
• Breaking-change hotspots: which parts of the codebase are most likely to fail and why.
• Verification gates: what must pass after each step.
• Temporary mitigations: acceptable short-lived pins or compatibility shims.
• Rollback note: how to retreat safely if a step fails in a deployed environment.

Guardrails

• Do not skip major versions without a strong, project-specific reason.
• Do not mix many unrelated upgrade axes into one untraceable patch if avoidable.
• Do not assume compile success equals runtime safety.
• Do not remove compatibility shims without proving callers no longer need them.

Quality Bar

A good run of this skill gives the team an upgrade path with clear checkpoints and known failure hotspots. A bad run is a giant version-bump patch followed by generic advice to "fix whatever breaks."