Cursor Incremental Dependency Migration Plan and Codemod Execution

Plans and executes a library or framework version migration in Cursor in small, verifiable batches, with an impact inventory, rollback points, and per-batch test gates instead of one risky bulk edit.

You get: Impact inventory table, phase plan table and phase 1 diff summary

More like this

The prompt

cursor-incremental-dependency-migration-plan-and-codemod-execution.md
Role: You are a migration engineer using Cursor Agent mode to upgrade {package_name} from {from_version} to {to_version} in {repo_name}.

Context: The decision to support is whether to migrate now, in phases, or defer. Use @Codebase to inventory usages, @Files for the changelog or migration guide I attach as {migration_doc}, and the terminal for the real build and test output. Do not invent breaking changes; cite only what the attached docs or the code show, and flag anything unverified.

Task: Produce an impact inventory and a phased migration plan, then execute phase 1 only after I confirm.

Inputs:
- Package and versions: {package_name}, {from_version} to {to_version}
- Migration guide or changelog: {migration_doc}
- Build command: {build_command}
- Test command: {test_command}
- Scope or directories: {scope_paths}
- Constraints (deadline, no API changes, supported runtimes): {constraints}
If an input is missing, list it under Missing information and state assumptions separately.

Workflow:
1. Inventory: use @Codebase to find all imports, call sites, config entries, and type usages of {package_name}. Group by pattern.
2. Map each pattern to a documented breaking change or mark it Unverified.
3. Rate each group by risk (Low, Medium, High) and effort (S, M, L).
4. Propose phases of at most ~15 files each, ordered from lowest to highest risk, with a test gate per phase.
5. Wait for my confirmation, then execute phase 1 as small diffs. Prefer a scripted codemod only when the pattern is uniform; show the script before running it.
6. Run {build_command} and {test_command}. Report real results and fix only failures caused by this phase.
7. Summarize the remaining phases and rollback steps.

Constraints:
- Do not bump the version in the manifest until phase 1 changes are ready and I approve.
- No unrelated refactors or formatting-only churn.
- Ask before running installs, lockfile updates, or commands that touch the network.
- Keep each phase independently revertible.

Output format:
1. Assumptions and Missing information
2. Impact inventory table: Pattern | Files | Documented change | Risk | Effort
3. Phase plan table: Phase | Scope | Test gate | Rollback step
4. Phase 1 diff summary: File | Change
5. Verification results
6. Risks and open questions
7. Next actions

Acceptance criteria:
- Every usage of {package_name} in scope appears in the inventory.
- Each phase has a test gate and a rollback step.
- Phase 1 builds and passes tests, or the failures are reported with causes.
- Unverified claims are labeled as such.

Quality checks:
- Did you search imports, dynamic requires, config files, and type declarations?
- Are peer dependency and runtime version impacts noted?
- Are deprecated but still working APIs separated from removed ones?
- Is the diff free of unrelated changes?

Example output

AI-written example
/**
 * codemods/phase1-cache-time-to-gc-time.js
 * Repo: acme-storefront | @tanstack/react-query 4.36.1 -> 5.51.0
 * Scope: src/lib/query, src/features/catalog
 * Build: pnpm build | Tests: pnpm test --run
 * Constraints: Node 18, no public API changes
 *
 * ASSUMPTIONS
 * - Lockfile and manifest stay on 4.36.1 until phase 1 is approved.
 * - Migration guide attached as docs/react-query-v5-migration.md.
 *
 * IMPACT INVENTORY (from @Codebase search, in scope)
 * Pattern                                 | Files | Documented change                        | Risk   | Effort
 * cacheTime option                        | 9     | Renamed to gcTime                        | Low    | S
 * useQuery(key, fn, opts) overloads       | 14    | Only object signature supported          | Medium | M
 * keepPreviousData: true                  | 4     | Removed; use placeholderData helper      | Medium | S
 * onSuccess/onError on useQuery           | 6     | Removed from queries                     | High   | L
 * isLoading on mutations                  | 3     | Renamed to isPending                     | Medium | S
 * Dynamic import("react-query") in tests  | 1     | UNVERIFIED (not in the attached guide)   | Medium | S
 *
 * PHASE PLAN
 * Phase | Scope                               | Test gate                     | Rollback
 * 1     | cacheTime -> gcTime (9 files)       | pnpm build && pnpm test --run | git revert <phase-1 commit>
 * 2     | Object signature + isPending (17)   | Same, plus typecheck          | git revert <phase-2 commit>
 * 3     | keepPreviousData, onSuccess removal | Same, plus manual smoke test  | git revert <phase-3 commit>
 *
 * Us
Generated from this prompt by AI. Your results will vary.

Tips and common edits

Attach the official migration guide with @Docs or @Files so Cursor works from real sources. Run the inventory step first and review it before approving phase 1. Commit after each phase so Cursor checkpoints and git history both give you rollback points.

Questions about this prompt

More in Cursor

Cursor Characterization-Test-First Refactor of a Legacy Module

Has Cursor lock in current behavior with characterization tests before restructuring a legacy module in small steps, so you can decide whether the refactor preserved behavior and is safe to merge.

Characterization Tests Before a Refactor

Writes tests that lock in a module's current behavior, including edge cases and quirks, so you can refactor safely.

Cursor Agent Bug Triage: Reproduce, Root-Cause, Fix, and Regression Test

Guides Cursor Agent through reproducing a bug, isolating the root cause with evidence, applying a minimal diff, and adding a regression test, ending with a verification checklist and risks.

Cursor Refactor of a Component With Zero Behaviour Change

Has the Cursor agent restructure a messy component into smaller pieces while proving the behaviour stays identical, using existing tests or new characterization tests first.

Unit Test Plan and Test Code for an Existing Function

Builds a behavior-based test matrix for a function or module and then generates test code in your framework. Covers edge cases, failures, and mocking boundaries, with coverage gaps stated honestly.

Codebase Tour for a Specific Task

Explores a repo through the lens of your task and explains the architecture, key files and data flow, then says where to start.

Coding Agent Task Brief with Guardrails, Test Plan, and Rollback Steps

Creates a scoped brief for an AI coding agent that limits file changes, defines tests, and includes a rollback plan and review checklist.

Cursor Project Rules Generator for Your Repo's Stack

Has Cursor inspect your repository and write 3-5 scoped .mdc rules, each with globs, a description and a deliberately chosen attach mode.

Dependency Graph Planner for a Multi-Agent Software Release Workflow

Turns a list of release tasks into a dependency graph with parallel batches, critical path, shared-resource conflicts, and agent assignments. Supports the decision on what to run now versus wait on.

Failing Test First Bug Fix

Reproduces a bug with a failing test, finds the root cause, applies the smallest fix and shows the test passing.

Plan Before Edit: Cursor Plan-Mode Prompt for a Feature Request

Produces a read-only Cursor plan listing files in scope, ordered steps, specific risks and tests to run before any code is changed.

Pull Request Review with Merge Recommendation

Reviews a diff against your standards and returns a merge, merge-with-changes, or do-not-merge recommendation. Findings are ranked by severity, with evidence, suggested fixes, and open questions.