api-contract-review

name	api-contract-review
description	review request, response, event, and schema contracts for compatibility and consumer safety. use when http, openapi, asyncapi, protobuf, json schema, generated clients, or external integration behavior changes.

API Contract Review

Trigger Signals

• the task changes HTTP routes, request or response shapes, headers, auth semantics, examples, or client SDKs
• the repo edits OpenAPI, AsyncAPI, Protobuf, JSON Schema, or generated contract code
• a versioning, deprecation, or compatibility question exists across providers and consumers

Inspect First

• source-of-truth specs and the runtime handlers that implement them
• schema validators, generated clients, examples, docs, and error-shape helpers
• versioning and deprecation notes, auth requirements, and pagination or idempotency behavior
• consumer code, integration tests, and release notes when a public contract changed

Workflow

1. identify the canonical contract surface and compare it to the implementation
2. classify the change by protocol: HTTP, event, schema-only, or wire-level
3. evaluate backward compatibility for required fields, enums, defaults, errors, and behavior semantics
4. verify examples, validation rules, and generated artifacts stay in sync
5. emit a consumer-centered review with specific remediation or rollout guidance

Output Contract

• changed contract summary grouped by endpoint, message, or schema
• compatibility verdict with the precise breaking edges called out
• consumer impact notes covering clients, codegen, docs, and deployment sequencing
• follow-up actions for linting, versioning, deprecation, migration guides, or tests

Failure Modes

• the runtime contract diverges from the checked-in spec and the source of truth is unclear
• examples, docs, or generated clients are stale enough that contract behavior cannot be trusted
• behavior semantics changed without any schema diff to explain it

Escalation

• escalate when a breaking change lacks versioning, deprecation, or migration guidance
• escalate when error semantics, auth requirements, or event-delivery guarantees change silently
• escalate when wire compatibility for protobuf or event consumers is uncertain

References

• skills/api-contract-review/references/http-contract-checklist.md
• skills/api-contract-review/references/schema-compatibility.md
• skills/api-contract-review/references/event-and-async-contracts.md
• skills/api-contract-review/references/protobuf-and-buf.md
• skills/api-contract-review/references/style-and-linting.md
• skills/api-contract-review/references/review-template.md
• skills/api-contract-review/references/examples.md