Research breaking changes

Turns release history and interface differences into a concrete migration impact map for your codebase.

migration-breaking-change-intelligence

See how it helps

When is it useful?

Use before upgrading a library across unfamiliar versions.

What does it help you do?

Maps every release boundary in the intended version span.
Inspects changed exports, types and configuration contracts.
Correlates reported regressions with actual project usage.

Try asking this

Research a library upgrade and list affected imports, required adaptations and unresolved upstream regressions. Map each discovered breaking change to a real call site. Mark irrelevant upstream changes separately and propose a small verification for every affected behavior.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

Migration & Breaking-Change Intelligence

Changelogs frequently omit subtle behavioral changes—altered default timeouts, stricter validation, changed error classes, or modified return semantics. When researching an upgrade or comparing versions, combine release notes with direct commit/diff inspection.

Workflow

Map the version span and release history:
- Identify the exact current version (vFrom) and target version (vTo), plus all intermediate major and minor releases.
- Read CHANGELOG.md, GitHub Releases, and official migration guides across every intermediate major version (e.g., upgrading v2 -> v5 requires checking v3, v4, and v5 breaking notes).
Inspect diffs on public entry points and types:
- Compare exported TypeScript definitions (.d.ts), public classes/functions, and configuration schemas between vFrom and vTo.
- Check for:
  - Removed or renamed exports, methods, and options.
  - Changed default values (e.g., retry: true -> false, timeout: 0 -> 30000, strict: false -> true).
  - Sync-to-async signature changes or Node/runtime minimum version bumps (engines field).
Search post-release issues for regression reports:
- Check issues opened shortly after vTo shipped. Early adopters often report undocumented breaking changes, memory regressions, or bundler incompatibilities before docs are updated.
Produce a concrete migration impact map:
- Cross-reference every upstream breaking change against our codebase's actual call sites (grep / AST search).
- Classify each impact as:
  - Zero-impact: Affects APIs we do not call.
  - Mechanical codemod: Simple rename or signature adjustment across $N$ call sites.
  - Behavioral / semantic shift: Requires adapter changes, config pinning, or new regression tests.
- Hand off the verified impact map to the dependency upgrade specialist or implementing developer.

Included files 1

SKILL.md