home / skills / shotaiuchi / dotclaude / refactor-compat
This skill verifies backward compatibility of public APIs and interfaces during refactors, guiding migration and preventing breaking changes.
npx playbooks add skill shotaiuchi/dotclaude --skill refactor-compatReview the files below or copy the command above to add this skill to your agents.
---
name: refactor-compat
description: >-
Backward compatibility verification for refactoring. Apply when checking
public API compatibility, exported interfaces, external contracts, and
identifying breaking changes requiring migration guides.
user-invocable: false
---
# Compatibility Checker Analysis
Verify backward compatibility for public APIs, exported interfaces, and external contracts.
## Analysis Checklist
### Public API Compatibility
- Check function signatures for parameter changes (order, type, count)
- Verify return type consistency across versions
- Detect removed or renamed public methods and properties
- Validate default value changes that alter existing behavior
### Interface Contracts
- Verify exported types and interfaces remain compatible
- Check protocol/trait implementations for missing methods
- Validate serialization format compatibility (JSON, protobuf, etc.)
- Ensure event schemas and message formats are backward compatible
### Breaking Change Detection
- Identify semantic changes that alter behavior without API changes
- Detect configuration format changes requiring user updates
- Find removed feature flags or environment variables
- Check database schema changes affecting existing data
### Migration Guide Requirements
- Define upgrade steps for each breaking change identified
- Provide deprecation warnings with recommended alternatives
- Plan compatibility shims for gradual consumer migration
- Document timeline for removing backward compatibility support
### Version Strategy
- Recommend semantic versioning impact (major, minor, patch)
- Plan deprecation period length based on consumer count
- Define compatibility testing matrix across supported versions
- Identify opportunities to batch breaking changes together
## Output Format
Report findings with impact ratings:
| Impact | Description |
|--------|-------------|
| Breaking | Incompatible change requiring all consumers to update |
| High | Behavioral change that may break consumers silently |
| Medium | Deprecation requiring consumer action within a timeline |
| Low | Compatible change with optional migration for improvement |
This skill verifies backward compatibility for public APIs, exported interfaces, and external contracts after refactoring. It helps teams detect breaking changes, rate their impact, and produce actionable migration guidance. Use it to prevent regressions that affect downstream consumers and to plan versioning decisions.
The skill inspects function signatures, return types, exported types, and public properties to flag removals, renames, and signature changes. It also validates serialization formats, event/message schemas, configuration and database schema changes, and detects semantic behavior changes that are invisible at the surface API level. Findings are reported with impact ratings and recommended upgrade steps.
What kinds of changes are reported as Breaking?
Removals or incompatible renames of public APIs, mandatory signature changes, or serialization/schema changes that invalidate existing consumer data.
How are impact ratings used?
Ratings guide versioning strategy and urgency: Breaking implies a major bump, High often suggests immediate attention, Medium signals planned deprecation, and Low requires no forced action.
Does the skill produce migration steps?
Yes. For each breaking or high-impact finding it recommends concrete upgrade steps, deprecation messages, and potential compatibility shim strategies.