Dependency Upgrade Prompt for Safe Package Bumps With a Plan

Dependabot opens a PR that bumps lodash from 4.17 to 5.0 and leaves you to discover, via a red CI run, that the package dropped the function you call in twelve places. A dependency upgrade prompt does the part the bot skips: it reads the changelog against your actual call sites and hands you a risk-tiered plan with the exact edits each bump needs before you touch CI.

Automated bumpers are great at noticing a new version exists. They're useless at telling you what it'll cost you. The PR says "4.17 → 5.0" and nothing about the three breaking changes that land in code you wrote. So the upgrade either sits ignored for months or gets merged on faith and breaks something downstream.

A reusable prompt turns a version number into a plan. Same structure every time: read the changelog, check it against your usage, tier the risk, list the edits.

Why a version bump isn't an upgrade plan

A bumped version in a manifest is a hope, not a plan. The real work is the diff between what the package used to do and what it does now, intersected with what your code relies on. A bot can't see that intersection because it never reads your call sites. It reads your package.json.

The opinionated take. Auto-merging dependency PRs is a habit that trades a small chance of a big break for the feeling of being current. For patch bumps with no breaking changes, fine, batch and merge them. For major versions, auto-merge is how a Friday deploy becomes a Saturday incident. The upgrade that needs human judgment is exactly the one a bot can't judge. A prompt restores the judgment by reading the changelog the way a careful engineer would.

What a dependency upgrade prompt does

A dependency upgrade prompt is a risk planner that reads a changelog plus your call sites and returns a tiered upgrade plan with the exact code edits each bump requires. It plans before it bumps.

Run it to:

• Inventory outdated dependencies into one structured report
• Score each upgrade by risk and surface breaking changes before any edit
• Cross-reference the changelog against your real call sites
• Batch safe patch bumps and sequence risky majors separately
• Output the exact code edits each breaking bump requires
• Generate a test checklist so CI failures are expected, not surprises

The call-site cross-reference is what a version bumper structurally can't do.

Anatomy of the prompt

Variables
  {{dependency}}        → package + current and target version
  {{changelog}}         → the release notes between versions
  {{call_sites}}        → where and how your code uses it
  {{lockfile}}          → for transitive impact (optional)

Prompt
  Role: you are a dependency upgrade planner.
  Task: plan the bump of {{dependency}} using {{changelog}}
        and {{call_sites}}.
  Rules:
    - Flag only breaking changes that touch the call sites.
    - Tier each bump: safe | review | risky.
    - List the exact edit each risky change requires.

Output contract
  Return: risk tier + affected call sites + edit list + test checklist.

1. Name the package and versions

Set {{dependency}} with current and target versions. "Bump it" without a target lets the model pick, which isn't your call to delegate.

2. Paste the changelog and your usage

{{changelog}} plus {{call_sites}} is the intersection that matters. The changelog alone tells you what changed; your call sites tell you what changed for you.

3. Read the risk tier

The output tiers the bump. A safe tier means batch it. A risky tier means it gets its own PR and its own review.

4. Apply the edit list

For risky bumps, the prompt returns the specific edits. Make them, then run the test checklist it generated.

Prompt-craft patterns for upgrades

Pass call sites, not just the changelog. A changelog read in isolation flags every breaking change, including the ten that don't touch your code. The {{call_sites}} variable filters to what's actually yours, which is the difference between a useful plan and noise.

Keep the test checklist even for safe tiers. A changelog can omit a breaking change. The test checklist is the backstop for the breaking change nobody documented. Don't let a safe tier skip it entirely.

Tier explicitly, three levels. Two levels (safe/unsafe) loses the middle case that needs a glance but not a full audit. Safe, review, risky maps to batch, check, isolate.

Where the model helps and where it can't

A dependency upgrade prompt is strong at the reasoning a bot skips: cross-referencing a changelog against your call sites and tiering the risk. It's weak exactly where the changelog is. If a maintainer shipped a breaking change without documenting it, the prompt won't see it, because the prompt only knows what's written. That's not a model limitation you can prompt around. It's a data gap.

So the test checklist isn't optional decoration. It's the backstop for the undocumented break. A good upgrade prompt treats the changelog as a strong hint, not a contract, and always emits tests that exercise the call sites it flagged. Claude tends to include the checklist when the rule asks for it; GPT-4o sometimes drops it on a safe tier unless you restate that every tier ships with tests. Pin the model version, because a planner that got more trusting of changelogs after an update will underbump risk in a way you won't notice until a safe batch breaks CI. Treat the prompt as a careful first reader, not the final word, and keep a human on the major bumps.

Variables you'll set

Getting started

1. Copy the structure into ChatGPT, Claude, or Gemini.
2. Set {{dependency}} with the current and target versions.
3. Paste the {{changelog}} and your {{call_sites}}.
4. Run it and read the risk tier before the edit list.
5. Batch the safe bumps, isolate the risky ones into their own PRs.
6. Apply the edits and run the generated test checklist.

To inventory every outdated dependency and get the batching and PR checklists generated for you, the Dependency Upgrade Harness Agent Pack runs the full workflow.

A dependency bump often forces a schema change or a framework move. The Database Migration Safety Harness applies the same risk-tiering to schema migrations. When an upgrade changes your own public API, the breaking change detection prompt maps the semver impact for your consumers. For staged framework moves, read the framework migration prompt. New to packs? See how to choose a reusable AI prompt pack.