# Upgrade Breaking Change Navigator > Plan and execute risky Spring Boot, Spring Framework, Kotlin, Gradle, JDK, and major dependency upgrades with explicit compatibility checkpoints and rollback thinking. Use when preparing or diagnosing a major version jump, navigating `javax` to `jakarta`, K2 adoption, plugin compatibility, auto-configuration drift, behavior changes in Hibernate or Security, or project-specific upgrade sequencing. - **Type:** Skill - **Install:** `agentstack add skill-yalishevant-kotlin-backend-agent-skills-upgrade-breaking-change-navigator` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [yalishevant](https://agentstack.voostack.com/s/yalishevant) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [yalishevant](https://github.com/yalishevant) - **Source:** https://github.com/yalishevant/kotlin-backend-agent-skills/tree/main/.agents/skills/upgrade-breaking-change-navigator ## Install ```sh agentstack add skill-yalishevant-kotlin-backend-agent-skills-upgrade-breaking-change-navigator ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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." ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [yalishevant](https://github.com/yalishevant) - **Source:** [yalishevant/kotlin-backend-agent-skills](https://github.com/yalishevant/kotlin-backend-agent-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-yalishevant-kotlin-backend-agent-skills-upgrade-breaking-change-navigator - Seller: https://agentstack.voostack.com/s/yalishevant - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.