API Contract Compatibility Review
Use current primary guidance as a review baseline, then report only what the available evidence supports. Primary authority: official reference.
Workflow
- Inventory producers, consumers, versions, transports, schemas, ownership, and independent deployment paths.
- Compare request, response, event, error, authentication, pagination, ordering, idempotency, and timing semantics.
- Identify additive, breaking, ambiguous, or behaviorally breaking changes, including optionality and default shifts.
- Review tolerant-reader assumptions, unknown fields, enum expansion, precision, units, locale, and time handling.
- Define contract tests and compatibility fixtures across old and new producer-consumer combinations.
- Specify negotiation, versioning, deprecation, rollout, telemetry, and rollback behavior.
- Separate documented contracts from accidental implementation behavior and unratified proposals.
Boundaries
- Do not call a change backward compatible from schema shape alone.
- Do not remove or reinterpret a field without consumer evidence and deprecation authority.
- Passing one consumer test does not prove compatibility for unknown consumers.
Output
Lead with the answer. Use the shortest format that retains the required evidence and limits; expand when requested or needed. The items below describe required content, not mandatory headings.
Return Contract inventory, Compatibility findings, Consumer risk, Test matrix, Rollout, Deprecation, and Unresolved authority. Grade each finding none, note, warning, or error, and order the list with the most severe first. Mark each finding new, unchanged, updated, or absent against the pinned base revision.
Example
Synthetic example; not an observed client result.
Input: In the supplied A-to-B API diff, total changes from an integer to a string. The supplied older client decoder requires an integer, and those clients remain deployed.
Output: error, new: the response type breaks the supplied older decoder. Contract inventory: A emits an integer; B emits a string; deployed older consumers require A. Evidence is the API diff and decoder contract. Test matrix: decode A and B responses with both old and new clients; results are pending. Preserve the existing type or add a compatible field, then verify consumer migration before deprecating the old contract. The rollout owner and migration completion are unresolved; this review authorizes neither rollout nor deprecation.
1---2name: review-api-compatibility3description: "Reviews breaking API, event, and schema changes when asked whether old clients still work or independent upgrades are safe; checks behavior and rollout order as well as field shapes."4license: MIT5metadata:6 source: https://skillmd.com/skills/jovanipink/review-api-compatibility7 author: "Measured Studios"8 version: "0.19.0"9 plugin: "measured-quality"10 invocation: "implicit"11 provenance: "original"12 risk_class: "read-only"13---1415# API Contract Compatibility Review1617Use current primary guidance as a review baseline, then report only what the available evidence supports. Primary authority: [official reference](https://www.rfc-editor.org/rfc/rfc9110.txt).1819## Workflow20211. Inventory producers, consumers, versions, transports, schemas, ownership, and independent deployment paths.222. Compare request, response, event, error, authentication, pagination, ordering, idempotency, and timing semantics.233. Identify additive, breaking, ambiguous, or behaviorally breaking changes, including optionality and default shifts.244. Review tolerant-reader assumptions, unknown fields, enum expansion, precision, units, locale, and time handling.255. Define contract tests and compatibility fixtures across old and new producer-consumer combinations.266. Specify negotiation, versioning, deprecation, rollout, telemetry, and rollback behavior.277. Separate documented contracts from accidental implementation behavior and unratified proposals.2829## Boundaries3031- Do not call a change backward compatible from schema shape alone.32- Do not remove or reinterpret a field without consumer evidence and deprecation authority.33- Passing one consumer test does not prove compatibility for unknown consumers.3435## Output3637Lead with the answer. Use the shortest format that retains the required evidence and limits; expand when requested or needed. The items below describe required content, not mandatory headings.3839Return Contract inventory, Compatibility findings, Consumer risk, Test matrix, Rollout, Deprecation, and Unresolved authority. Grade each finding `none`, `note`, `warning`, or `error`, and order the list with the most severe first. Mark each finding `new`, `unchanged`, `updated`, or `absent` against the pinned base revision.4041## Example4243Synthetic example; not an observed client result.4445Input: In the supplied A-to-B API diff, `total` changes from an integer to a string. The supplied older client decoder requires an integer, and those clients remain deployed.4647Output: error, new: the response type breaks the supplied older decoder. Contract inventory: A emits an integer; B emits a string; deployed older consumers require A. Evidence is the API diff and decoder contract. Test matrix: decode A and B responses with both old and new clients; results are pending. Preserve the existing type or add a compatible field, then verify consumer migration before deprecating the old contract. The rollout owner and migration completion are unresolved; this review authorizes neither rollout nor deprecation.