interface-contract-design
Interface Contract Design
Define what a boundary promises before anything implements or consumes it. Boundaries designed implementation-first leak internals into the contract and leave error semantics, idempotency, and versioning to be discovered by the first outage.
When to Use
Use when a new boundary (API, service interface, module seam, message schema, webhook) needs its contract defined, or an existing contract description needs an audit, before implementation. Out of scope: implementing the boundary, generating client/server code or formal schema files (OpenAPI, protobuf) — this skill produces the contract decisions those artifacts encode; language-specific binary-compatibility concerns; and auth-protocol internals beyond naming what the contract requires from them.
Input modes:
- Design mode: boundary purpose, consumers, and constraints supplied. Produce the contract.
- Audit mode: an existing contract description supplied. Reproduce it restructured into the contract fields (full template, including the
Idempotency:line per operation) and list every gap under### Contract gaps.
Missing consumers do not block either mode: write none named in input on the Consumers line and add a ### Contract gaps entry naming the unconfirmed consumer set. The BLOCK template is only for a missing boundary description.
Required Inputs
- The boundary's purpose and its known consumers, or the existing contract text to audit.
- Constraints when supplied: latency budgets, payload limits, compatibility requirements, project API conventions.