On bad output, see guides/skill-recovery.md

Dependency Upgrade Evaluation

Surface risks, breaking changes, and migration effort so the user can decide. Do not rubber-stamp or block reflexively.

Scoping

Determine what you're evaluating:

1. User names a specific upgrade (e.g., "upgrade React from 17 to 18"): evaluate that version transition.
2. User asks generally (e.g., "should we upgrade lodash"): check current version, latest version, evaluate the gap.
3. Security advisory: focus on the vulnerability, affected versions, and minimum upgrade path to resolve it.

Gather information

Current state in the project:

• Current version? (Check package.json, go.mod, requirements.txt, Cargo.toml, etc.)
• How used? Search codebase for imports/requires. Note which APIs/features are actually used — this determines which breaking changes matter.
• Any version pins, overrides, or resolutions constraining the upgrade?

Upgrade target:

• Target version? (Latest stable, specific version, or minimum version fixing a vulnerability)
• Versions between current and target? (Major jumps may require stepping through intermediate versions)

Changelog and migration guides:

• Use web search to find the changelog, release notes, and migration guides.
• Focus on breaking changes, deprecations, new requirements (minimum runtime version, peer dependency changes, dropped platform support).

Execution evidence protocol

Governs standalone mode — when no code-fact-check report is in context. (When one is provided, it is the sole source of execution results; cite its claim ids and skip this protocol.)

Any statement of the form "command X produced result Y" that supports a verdict is an execution claim — including "quiet" results like an audit reporting nothing or a grep finding no matches. An execution claim is only expressible with its provenance attached:

• (a) the exact command,
• (b) cwd + commit SHA + lockfile hash,
• (c) exit code,
• (d) timestamp,
• (e) for audit commands, the advisory-database/registry state the tool reports,
• (f) the raw output — verbatim and complete inline for short read-only commands; captured to docs/reviews/{branch}/evidence/{n}-{cmd-slug}.txt for verdict-bearing gates (audit, install, test).

Paraphrased output — "(no output — exit 0)" — is never provenance. If you cannot attach provenance, the only permitted phrasing is: Unverified — run `<cmd>` and attach output before relying on this.

Analysis

1. Breaking changes impact

For each breaking change between current and target:

• Affects this project? Check whether the project uses the changed API. Many breaking changes are irrelevant to a codebase.
• Migration path? Mechanical rename, behavioral change, or conceptual redesign?
• Codemod or migration tool? Many major upgrades provide automated migration.

Rate overall impact: None (no relevant breaking changes), Mechanical (find-and-replace or codemod), Moderate (thoughtful but straightforward changes), Significant (rethink how the dependency is used).

2. Transitive dependency effects

• Will it force upgrades of other dependencies? (Peer dependency changes)
• Does it conflict with other dependencies? (Version resolution conflicts)
• Does it change minimum runtime or platform requirements?

3. Risk assessment

What could go wrong?

• Subtle behavioral changes — not breaking in the API sense but changing outcomes
• Performance regressions (especially core deps: ORMs, HTTP clients, bundlers)
• Compatibility issues with the runtime environment
• Incomplete migration leaving the codebase half-upgraded

How detectable are problems?

• Tests that would catch behavioral regressions?
• Type checks that would surface API changes at compile time?
• Would problems manifest immediately or only under specific conditions?

4. Urgency

• Security vulnerability with known exploits → urgent
• Security advisory without known exploits → soon, not emergency
• End-of-life / no longer patched → plan the upgrade
• New feature the project needs → upgrade when needed
• Keeping up with latest → low urgency; evaluate cost/benefit
• Dependency of a dependency requires it → check if avoidable

5. Rollback rehearsal (precondition)

Before starting the migration, the rollback procedure must be documented and rehearsed. An upgrade you don't know how to undo isn't safe to start.

• Documented means writing the exact commands that revert the change: lockfile/version pin restoration, the install command, and any data/config changes to unwind. Vague intent ("revert the commit") doesn't count — write the literal commands.
• Rehearsed means running those commands once and confirming a verification step passes afterward. Keep it small but real: a smoke test, an app boot, a focused test exercising the dependency's primary use. Pick something that would fail if the rollback left the project broken.
• Rehearse on a scratch branch (or equivalent) so the rehearsal doesn't destabilize ongoing work. The artifact is the "rehearsed on {date/branch}, verification passed" line in the output template — itself an execution claim, so it carries the verification step's captured output (evidence path or verbatim) per the execution evidence protocol.

Why a precondition, not a follow-up: rehearsing after a problem occurs is when you discover the lockfile doesn't fully revert, a database migration was one-way, or the install command needs a forgotten flag. Find those problems while the upgrade hasn't shipped yet.

Output

## Dependency Upgrade Evaluation: {package} {current} → {target}

### Summary
**Recommendation:** {Upgrade now / Upgrade soon / Defer / Don't upgrade}
**Breaking change impact:** {None / Mechanical / Moderate / Significant}
**Estimated effort:** {minutes / hours / days}
**Risk:** {Low / Medium / High}
**Audit state:** {as of YYYY-MM-DD HH:MM, advisory DB {metadata} — re-run at merge if >24h old or lockfile changed} / {Consumed from code-fact-check report, claims {ids}} / {Unverified}

### Motivation
{Why is this upgrade being considered? Security? New features? Staying current?}

### Breaking Changes That Affect This Project

| Change | Affected code | Migration |
|--------|--------------|-----------|
| {API removed/renamed/changed} | {files in this project that use it} | {what to do} |

{If no relevant breaking changes: "No breaking changes affect this project's usage."}

### Breaking Changes That Don't Affect This Project
{List briefly, so the user knows they were checked and dismissed, not overlooked.}

### Transitive Effects
- {Peer dependency changes, version conflicts, runtime requirements, or "None identified"}

### Execution Evidence

| Command | Exit | As-of | Evidence |
|---------|------|-------|----------|
| {exact command} | {exit code} | {timestamp + advisory-DB state where applicable} | {fact-check claim id / evidence-file path / verbatim inline output} |
| {command not run and not citable} | — | — | Unverified — recommended pre-merge check |

No cell may be filled from memory or assumption — every row's evidence is a fact-check claim id, an evidence-file path, or verbatim inline output; anything else renders as `Unverified — recommended pre-merge check`.

### Risk Factors
- {Behavioral changes, performance concerns, compatibility issues, or "Low risk — well-tested upgrade path"}

### Rollback Plan (precondition — complete before starting Migration Plan)

**Exact rollback commands:**
```
{e.g.,
git checkout -- package.json package-lock.json
npm ci
# if a data/config change was applied:
{exact undo command}
}
```

**Verification step** (run after rollback; must pass to confirm rollback worked):
{e.g., `npm test -- src/payments` — exercises the dependency's primary use in this project; would fail if the lockfile didn't fully revert.}

**Rehearsal status:** [ ] Rehearsed on {YYYY-MM-DD} on branch `{scratch-branch-name}`; verification step passed — evidence: {evidence-file path or verbatim verification output}.

### Migration Plan
{If recommending upgrade, provide concrete steps:}
1. {Step 1 — e.g., "Update version in package.json"}
2. {Step 2 — e.g., "Run codemod: npx @org/migrate"}
3. {Step 3 — e.g., "Update `createClient()` calls to pass config object instead of positional args (3 call sites)"}
4. {Step 4 — e.g., "Run tests, check for deprecation warnings"}
5. {Step 5 — e.g., "Remove compatibility shim added in v3 migration"}

### If Not Upgrading
{If recommending deferral, note what would change the recommendation — e.g., "Revisit when
we start the API v3 work, which will require the new streaming API in this dependency."}

Comparison mode

When the user compares 2+ options ("should we upgrade or switch to a different library"), produce one evaluation block per option using the template above, then add a final comparison block:

## Comparison Summary

| Option | Recommendation | Breaking change impact | Effort | Risk | Why |
|--------|---------------|------------------------|--------|------|-----|
| {dep@target} | Upgrade now | Mechanical | hours | Low | {1-line reason} |
| {alternative-dep} | Defer | Significant | weeks | Medium | {1-line reason} |

**Recommended option:** {which one and why — reference the rows above}

Keep each per-option evaluation complete (header, Summary, Breaking Changes…, Migration Plan, etc.) so reviewers see the full reasoning behind each row, not just the verdict.

Output Location

Present the evaluation in chat. If the user requests a persisted artifact, save to docs/working/dep-upgrade-{package}-{version}.md.

Important

• Search the codebase for actual usage. Don't evaluate breaking changes in the abstract — check whether the project uses the affected APIs. A "major breaking change" the project doesn't touch is irrelevant.
• Read the migration guide, not just the changelog. Changelogs list what changed; migration guides explain how to adapt. Base the effort estimate on the migration path, not the changelog length.
• Check for codemods. Many libraries provide automated migration tools. A breaking change with a codemod is mechanical work, not a design challenge.
• Don't recommend upgrading just to be current. Every upgrade has nonzero risk and effort. The benefit should justify the cost. "It's the latest version" is not sufficient motivation.
• For security upgrades, check the actual advisory. Is the vulnerability exploitable in this project's usage? A vulnerability in a feature the project doesn't use may not require an emergency upgrade. Advisory data is time-varying: an audit result is a snapshot, not a property of the branch. Scope every audit-derived verdict "as of {timestamp / advisory-DB state}" and state the re-run trigger: re-run the gate at merge time if the review is older than 24h or the lockfile changed since.
• Run the security-reviewer skill on the resulting diff before recommending merge when the upgrade is motivated by a CVE, replaces a security-relevant package, or bumps crypto/auth dependencies. This is the symmetric counterpart to security-reviewer's own dep-manifest trigger — that flags risks at manifest-change time; this catches issues introduced by the call-site migration itself.
• When the upgrade path is unclear, recommend a spike. If you can't confidently estimate the effort, say so and suggest a timeboxed investigation using the spike workflow.
• Don't start the migration until the rollback is documented and rehearsed. A rollback that's never been executed is not a rollback plan — it's a hope. Rehearse on a scratch branch and confirm a verification step passes before touching the real upgrade.
• Never present a command you did not run in this session as having been run. If a result is remembered, inferred, or expected, it is a prediction — label it as such. The evidence protocol exists because a fabricated "exit 0" once became a shipped "gate passes" rubric row (secdeps N2, 2026-04-27).