---
name: tobihagemann/update-dependencies
source: https://app.decimal.ai/s/tobihagemann-update-dependencies@4/SKILL.md
source_sha256: ab685e308ca1
---

# Update Dependencies

Upgrade project dependencies, researching breaking changes for major version updates.

Optional filter: `$ARGUMENTS` (e.g., `react`, `Alamofire`, `serde tokio`)

## Phase 1: Review Dependencies

Run the `$review-dependencies` skill to detect package managers and discover available updates. If no updates are available, stop.

## Phase 2: User Strategy Selection

Present a summary showing:
- Count and list of major updates (with current → target versions)
- Count of minor updates
- Count of patch updates

Use `request_user_input` for upgrade strategy (Codex `request_user_input` allows up to 3 options per question, so the strategies are split across two questions):

**Question 1 — Header**: "Approach"
**Options**:
- **Cautious** — Upgrade minor/patch first, then major one-by-one with research
- **All at once** — Research all major changes, then upgrade everything together
- **Major handling** — Defer the major decision (Skip-major or Interactive)

When a major upgrade would force a migration that is costly to reverse, present a **Get a second opinion** option in place of **All at once**, keeping Question 1 at three options and leaving **Major handling** in place so Question 2 stays reachable. It runs the `$consult-claude` skill for which strategy the breaking changes warrant. Then resolve the strategy with that answer in hand, re-asking when the choice stays the user's. A freeform answer asking to upgrade everything together selects the All-at-once strategy.

If the user picks **Major handling**, ask a follow-up:

**Question 2 — Header**: "Major handling"
**Options**:
- **Skip major** — Only upgrade minor and patch versions
- **Interactive** — Ask for each major update individually
- **Cancel** — Cancel and return to the previous step

## Phase 3: Research Breaking Changes

For **each package with a major version update**:

### Step 1: Calculate Version Gap

Identify all major versions between current and target. For example:
- `react: 17.0.2 → 19.0.0` → research v18 AND v19 breaking changes
- `Alamofire: 4.9.1 → 6.0.0` → research v5 AND v6 breaking changes

### Step 2: Research Each Major Version

Search for migration documentation:

```
Web search: "[package-name] v[X] migration guide"
Web search: "[package-name] v[X] breaking changes"
```

Common sources: GitHub releases page, official docs, changelog files.

### Step 3: Extract Key Breaking Changes

Identify: API changes (renamed/removed functions), configuration changes, peer/transitive dependency requirements, behavioral changes, deprecated features now removed.

### Step 4: Search Codebase for Affected Code

Use `rg` to find usage of deprecated or changed APIs. Document which files are affected and what changes are needed.

## Phase 4: User Confirmation

For each major update, present:
- Package name and version transition
- Breaking changes found (summarized)
- Files potentially affected (count and list)

Use `request_user_input` to confirm (Codex `request_user_input` allows up to 3 options per question, so the four actions are split across two questions):

**Question 1 — Header**: "Decision"
**Options**:
- **Proceed** — Continue with upgrades and migrations
- **Show details** — Display detailed breaking changes for review
- **Other action** — Defer the choice (Skip-package or Abort)

If the user picks **Other action**, ask a follow-up:

**Question 2 — Header**: "Other action"
**Options**:
- **Skip package** — Exclude a specific package from upgrade
- **Abort** — Cancel the upgrade process
- **Cancel** — Cancel and return to the previous step

If "Show details" selected, display full migration research, then ask again.

## Phase 5: Execute Upgrades

### Cautious Strategy

First upgrade minor and patch only using the package manager's semver-respecting update command, then run tests. If tests fail, stop before proceeding with major upgrades.

### Major Version Upgrades

Update the manifest file (version constraint) and run the install/resolve command. For package managers with a dedicated upgrade command, use it. For others (Swift PM, Maven, Gradle), edit the manifest directly.

## Phase 6: Apply Migrations

### Step 1: Run Codemods (if Available)

Some ecosystems provide automated migration tools:

| Ecosystem | Migration tools |
|---|---|
| React | `npx react-codemod [transform]` |
| Next.js | `npx @next/codemod [transform]` |
| Jest | `npx jest-codemods` |
| Angular | `npx ng update` |
| Rust | `cargo fix` for edition migrations |
| Python | `pyupgrade`, `python-modernize` |

### Step 2: Manual Code Changes

For changes requiring manual intervention:
1. Read the affected file
2. Apply the necessary transformation with `apply_patch`
3. Show the user what changed

### Step 3: Update Configuration Files

If configuration format changed, read current config, transform to new format, write updated config.

### Step 4: Sync Version-Pinned CI/Container References

Some packages pin their version outside the manifest, beyond the package manager's reach, so a green local run hides the drift. For every upgraded package (major, minor, or patch), search CI and container configs for the old version string with `rg "<old-version>" .github Dockerfile* docker-compose* .devcontainer` and bump it in lockstep:

- CI container images whose tag must track the package — e.g. a Playwright image tag kept in lockstep with the installed `@playwright/test` version.
- Base images and tool versions in `Dockerfile`, `.devcontainer/`, and `docker-compose.yml`.
- Pinned tool versions in CI setup steps (`actions/setup-node` `node-version`, `setup-python`, toolchain files).

## Phase 7: Verification

Run the project's test, build, and lint commands. Detect which commands are available from the project's config files and scripts. Use project-level task runners when present (`Makefile`, `Taskfile`, `justfile`, npm scripts, etc.).

### Report Results

Summarize: packages upgraded (count), breaking changes addressed (count), files modified (count), test results, remaining manual tasks.

### Recommend Next Steps

If any migrations could not be automated:
- List specific changes the user needs to review
- Highlight deprecated patterns that need attention
- Note any runtime behavior changes to watch for

## Error Handling

### Discovery Tool Not Available

If the discovery tool is not installed, `$review-dependencies` will note it. Fall back to manual version checking via web search.

### Network Errors During Research

If web search/fetch fails: retry with alternative search terms, provide manual research links, proceed with caution warning that migration research may be incomplete.

### Test Failures After Upgrade

- Stop the upgrade process
- Suggest rollback: restore manifest and lockfile from git, then reinstall
- Identify which package likely caused the failure

### Migration Research Incomplete

If official migration docs are not found: check the package's repository for issues and discussions, note as "migration research incomplete — proceed with caution."