# Dependency Upgrade Migration Planner

Plan a safe library, framework, or runtime upgrade by mapping breaking changes, compatibility risks, tests, and rollback steps.

## Prompt

You are a software modernization engineer who specializes in high-confidence dependency and framework upgrades.

Inputs:
1. Dependency or runtime and current-to-target versions: {{upgrade_target}}
2. Application architecture and usage patterns: {{application_context}}
3. Release notes, deprecations, and migration guidance: {{change_information}}
4. Test coverage, deployment process, and environments: {{delivery_context}}
5. Compatibility, downtime, and deadline constraints: {{constraints}}

Do the following:
1. Inventory the application's direct and transitive use of the dependency, including APIs, configuration, plugins, generated code, build tools, and runtime assumptions.
2. Convert relevant breaking changes and deprecations into a compatibility matrix that identifies affected components, evidence, required code changes, and unknowns needing experiments.
3. Design the smallest safe sequence of upgrade steps, separating mechanical changes from behavioral changes and avoiding unrelated refactors.
4. Define compile, unit, integration, contract, performance, security, and production-smoke tests, with special attention to changed defaults and silent behavior differences.
5. Produce a migration checklist, risk-ranked work plan, dependency-conflict strategy, staged rollout, observability checks, and rollback procedure. Cite supplied migration guidance and label any inferred change.

## Best for

Engineering teams upgrading important dependencies without mixing migration risk with unnecessary code modernization.

## Compatible tools

- Claude
- ChatGPT

## How to use

- Provide current and target versions plus lockfiles.
- List custom extensions and unusual usage patterns.
- Attach official migration notes when possible.
- Keep unrelated refactoring out of the upgrade branch.

## Customization tips

- Include transitive dependencies and build plugins.
- Call out changed defaults, not only removed APIs.
- Specify database migration reversibility.
- Use canary metrics tied to known behavioral risks.

## Example input

Upgrade: Django 3.2 to 5.0. Context: 14-service monorepo, custom authentication backend, Celery tasks, PostgreSQL, and 63 third-party packages. Change information: Python 3.10 minimum, removed APIs, timezone behavior updates, and storage configuration changes. Delivery: 78% unit coverage, staging environment, weekly releases, canary deployment. Constraints: no customer downtime, complete within eight weeks, and preserve existing API behavior.

## Example output

The plan first upgrades Python and dependencies while keeping Django 3.2, then moves through Django 4.2 LTS before 5.0 to isolate failures. The matrix flags custom authentication, timezone comparisons, file storage settings, and incompatible plugins. It adds contract tests for public APIs, task serialization tests, timezone boundary cases, and canary metrics for 5xx rates and task failures. Each phase has a lockfile, reversible database policy, and rollback to the previous image.