playbooks

home / skills / shotaiuchi / dotclaude / migration-breaking

migration-breaking skill

/dotclaude/skills/migration-breaking

This skill analyzes migration changes to identify breaking API, behavioral, or removal risks, guiding safe upgrades.

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

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

Files (1)
SKILL.md
1.6 KB
---
name: migration-breaking
description: >-
  Breaking change analysis for migrations. Apply when cataloging incompatible
  API changes, removed features, behavioral differences, deprecated usage,
  and version-specific breaking changes.
user-invocable: false
---

# Breaking Change Analysis

Analyze code for breaking changes during migration.

## Migration Checklist

### API Incompatibilities
- Identify changed method signatures and return types
- Catalog removed or renamed public APIs
- Check for changed default parameter values
- Verify event and callback contract changes

### Removed & Deprecated Features
- List all removed APIs with replacement alternatives
- Identify deprecated features scheduled for removal
- Check for removed configuration options
- Verify removed CLI flags or environment variables

### Behavioral Changes
- Detect changed error handling semantics
- Identify altered sorting, ordering, or iteration behavior
- Check for changed concurrency or async behavior
- Verify modified lifecycle hook timing or order

### Type & Signature Changes
- Identify changed generic type parameters
- Check for narrowed or widened type constraints
- Verify changed nullability annotations
- Detect incompatible interface or protocol changes

## Output Format

Report findings with risk ratings:

| Risk | Description |
|------|-------------|
| Critical | Binary or runtime incompatibility, blocks migration |
| High | Significant behavioral change, likely causes bugs |
| Medium | Subtle change, may cause issues in edge cases |
| Low | Minor change, unlikely to cause problems |

Overview

This skill performs breaking change analysis tailored for migrations. It inspects code, APIs, configurations, and behavioral contracts to identify incompatible changes that could block or degrade migrations. The goal is a prioritized, actionable report that highlights critical risks and suggested remediation paths.

How this skill works

The skill scans source files, public interfaces, and configuration surfaces to detect removed or renamed APIs, signature and type changes, and altered default behaviors. It cross-references deprecated features, CLI flags, and environment variables, then assesses behavioral and lifecycle differences such as error handling, ordering, and concurrency changes. Findings are categorized with risk ratings and clear replacement or mitigation suggestions.

When to use it

  • Before upgrading a library, framework, or platform version
  • When preparing migration guides or release notes
  • During code reviews for breaking-change PRs
  • To audit third-party dependency updates for compatibility
  • When rebasing large codebases onto a new major version

Best practices

  • Run analysis early and iterate as code or dependency changes land
  • Combine static inspection with targeted runtime tests for high-risk areas
  • Document each breaking change with a clear replacement or shim option
  • Prioritize fixes using the risk rating: start with Critical and High items
  • Keep a migration checklist per module: API, config, behavior, types

Example use cases

  • Cataloging removed public APIs after a major library upgrade and listing replacements
  • Detecting changed function signatures and generating a patch list for calling sites
  • Finding altered default configs or flags that could change runtime behavior
  • Identifying lifecycle or concurrency changes that require test refactors
  • Preparing a migration report that groups issues by risk and remediation effort

FAQ

How are risk ratings determined?

Risk is based on impact and likelihood: Critical for runtime-breaking issues, High for likely bug-causing behavior changes, Medium for edge-case issues, and Low for minor, low-impact changes.

Does the skill run tests or only static checks?

It primarily performs static inspections and contract checks but recommends targeted runtime tests for Critical and High findings to validate actual impact.