playbooks

home / skills / shotaiuchi / dotclaude / migration-resolver

migration-resolver skill

/dotclaude/skills/migration-resolver

This skill helps resolve dependency conflicts during migrations by analyzing version constraints, transitive risks, and peer requirements to ensure safe

npx playbooks add skill shotaiuchi/dotclaude --skill migration-resolver

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.7 KB
---
name: migration-resolver
description: >-
  Dependency resolution for migrations. Apply when resolving version conflicts,
  transitive dependency issues, peer dependency requirements, and incompatible
  dependency trees.
user-invocable: false
---

# Dependency Resolution

Resolve dependency conflicts during migration.

## Migration Checklist

### Version Conflict Resolution
- Identify direct dependency version incompatibilities
- Resolve conflicting version ranges across packages
- Verify pinned versions are compatible with target migration
- Check for version constraints that block upgrading

### Transitive Dependencies
- Map the full transitive dependency tree for changes
- Identify indirect dependencies pulled in by upgrades
- Check for diamond dependency conflicts
- Verify transitive dependency licenses remain compliant

### Peer Requirements
- Validate peer dependency ranges after version bumps
- Identify unmet peer dependency warnings
- Check for plugins or extensions requiring specific peer versions
- Ensure peer dependency declarations are updated in package metadata

### Dependency Tree Health
- Audit for known vulnerabilities in updated dependencies
- Check for abandoned or unmaintained dependencies
- Verify no duplicate packages exist at incompatible versions
- Validate the lock file is consistent and reproducible

## Output Format

Report findings with risk ratings:

| Risk | Description |
|------|-------------|
| Critical | Unresolvable conflict, blocks migration entirely |
| High | Conflict requires major refactoring or replacement |
| Medium | Conflict resolvable with version pinning or overrides |
| Low | Minor version bump, no conflicts expected |

Overview

This skill performs dependency resolution focused on migrations. It identifies version conflicts, transitive issues, peer dependency problems, and overall dependency tree health to produce actionable remediation guidance. The skill outputs findings with clear risk ratings to prioritize fixes during a migration.

How this skill works

The skill inspects direct and transitive dependency graphs, evaluates version ranges and pinned versions, and validates peer dependency declarations. It audits lock files, checks for duplicate or abandoned packages, and flags vulnerabilities and licensing concerns. Results are summarized with risk levels and recommended actions for each issue.

When to use it

  • Before upgrading major framework or library versions during a migration
  • When resolving build or runtime errors caused by dependency changes
  • While preparing release branches to ensure reproducible installs
  • If peer dependency warnings appear after bumping packages
  • When transitive upgrades introduce unexpected behavior or license changes

Best practices

  • Map the full dependency tree to understand direct and indirect impacts
  • Prefer small, incremental version bumps and validate tests after each change
  • Use lock files and CI reproducible installs to avoid environment drift
  • Document overridden or pinned versions and reasons for future audits
  • Prioritize critical and high risks that block migration before medium and low

Example use cases

  • Resolve conflicting semver ranges between multiple packages preventing an upgrade
  • Detect diamond dependency conflicts where two packages require incompatible sub-dependencies
  • Validate peer dependency ranges for plugins after core library major version bumps
  • Identify abandoned or vulnerable transitive dependencies that need replacement
  • Confirm lock file consistency before cutting a migration release

FAQ

How are risk ratings determined?

Risk is based on impact and fixability: Critical blocks migration, High needs major changes, Medium can be resolved with pinning/overrides, Low is minor and low-risk.

Can this skill automatically fix conflicts?

It recommends concrete fixes such as version pins, overrides, or replacements but does not change repositories automatically; apply changes after review and CI validation.