API Contract Compatibility Review

Use this skill when the main risk is breaking consumers through interface changes.

Trigger Conditions

Use this skill when:

• request or response shapes are changing
• schema, event, or payload contracts may break old clients or downstream services
• the user asks whether a change is backward compatible
• versioning, migration, or deprecation strategy needs review
• integration risk matters more than internal implementation details

Do not use this skill for generic refactor planning or dependency/license review.

Workflow

1. Identify the contract under change.
2. Compare current and proposed behavior or shapes.
3. Check backward and forward compatibility risks.
4. Identify affected consumers, migration needs, and deprecation concerns.
5. Recommend versioning or rollout safeguards.
6. Suggest verification and communication steps.

Output

For non-trivial work, provide:

• contract surface reviewed
• compatibility risks
• likely breaking changes
• migration or versioning guidance
• verification focus
• recommended next action

Coordination

After contract review:

• use change-impact-analysis if the consumer surface is still unclear
• use release-rollout-strategy when compatibility risk changes rollout shape
• use docs-writer when migration guidance or deprecation notes should be published

Invocation Examples

• "Use api-contract-compatibility-review to check whether this endpoint change breaks old clients."
• "Use api-contract-compatibility-review on this event schema update before release."
• "Use api-contract-compatibility-review and tell me whether we need versioning or migration guidance."