API Contract Guard

What does this interface promise — and which of those promises can never be taken back?

Code is cheap to change, and a promise to someone who deploys on their own schedule is not. Once a mobile build ships, a partner integrates, or a webhook receiver is written against a payload, every field name, status code and retry behavior carries weight. We'll fix it in v2 means running v1 for years.

Coding agents produce endpoints well. What they miss is that this endpoint is the first in the API to use offset pagination where the others use cursors, or that POST /refunds without an idempotency key will refund twice on the client's first retry.

The deliverable is a short block of decisions, written before the code:

CONTRACT  GET /v1/invoices — public, API-key clients
FOLLOWS   error envelope {error:{code,message}} (src/api/errors.js:3) · cursor
          pagination ?cursor=&limit=, max 100 (GET /v1/payments) · amounts as
          integer minor units + currency · timestamps ISO-8601 UTC
DECIDES   order by (created_at, id) so cursors stay stable under inserts ·
          status is an open enum, clients must tolerate new values · another
          customer's invoice returns 404, identical to a missing one
CHANGE    additive
HANDOFF → proof-driven-dev: contract tests for page stability and cross-customer 404

Activation

Engage when a change adds or alters an interface that someone else deploys against: a public or partner HTTP or GraphQL API, a webhook sent or received, an event or message another service consumes, a published SDK or library API, CLI output or exit codes that scripts parse, a file format others import. Also engage on changes to the response shape, status codes, errors, pagination, authentication or versioning of such an interface.

Stay quiet when every consumer ships in the same deploy, such as an internal endpoint only this repository's own frontend calls, unless old clients outlive a deploy (cached single-page apps, installed mobile builds). Also stay quiet for internal functions and modules, whose callers are Impact Map's concern, for UI-only work, and for refactors behind an unchanged interface.

Depth CONSULT: the decisions block, then the work. ACTIVE when designing a new public API or making a breaking change. Never GATING.

Composes with impact-map (who consumes the interface today, found in the repository; this skill decides what it should promise) · proof-driven-dev (each decision becomes a contract test) · production-guard (verifies idempotency and retries after the fact) · standards-compass (authorization, rate limiting and data exposure: the security half of an API stays there).

Working with the other Skills Hub skills

• Loaded is not engaged. This file stays in context once loaded. Decide again on every new request whether it applies. Relevance to an earlier request carries nothing forward. Project state persists, and engagement does not.
• Depth. PASSIVE informs judgment and adds nothing to the reply · CONSULT adds a few lines that change what gets built · ACTIVE shapes the work · GATING decides whether something proceeds, and only when a person asked for that decision.
• Announce once. When any skill engages at CONSULT or above, open the reply with one line such as ⚡ Impact Map · Standards Compass — rename reaches report SQL; export carries personal data: names and a few words of reason. Never include reasoning. Add no line for PASSIVE, and none on a trivial request. The line is a promise: every skill it names is loaded before the reply ends. If one turns out not to apply, say so in one line: <Skill> dropped: <reason>.
• One interruption per request. Skills that must speak before the work share one short block. Everything else arrives with the work.
• Hand off; don't absorb. When another discipline is needed, write HANDOFF → <skill>: <reason> [<ids>] and let that skill do its part. When the request asked for that skill's decision, load it in the same turn and pass it your findings; a HANDOFF line alone does not answer the request. Never state another skill's verdict yourself. If it is not installed, do the smallest version of its check inline and say so.
• Conflicts. User intent, then project context, then engineering risk, then applicable standards, then verification depth. Each skill keeps its own verdict, and none overrules another's.
• Overrides. "Use X" engages X. "Skip X" or "no review" drops X's ceremony. Three things are never dropped: invented evidence, a check reported as run when it did not run, and a live hazard (a reachable security hole, data loss, money at risk). A live hazard is said once, in one line.
• State. Read what sibling skills recorded (.project-compass/, .project-standards/, .proofbuild/, .agent-investigation/) rather than re-deriving it. Write only your own.
• Lessons. On engaging, read ~/.skills-hub/lessons/<this skill's name>.md if it exists. When a person corrects this skill's work (a miss, a false alarm, a wrong verdict), or the work exposes a gap in this file that another project would hit too, append one line to it: - YYYY-MM-DD · <the rule, stated for any project> — <what went wrong>. Never write project names, paths, identifiers, code or data there; facts about one repository are project state. Keep at most 20 lines, merging or replacing one to add another. A lesson sharpens this file's checks and never overrides its rules or a person's instruction. The file sits outside every project, so no read-only rule covers it. Say Lesson recorded: <rule> once; if the file cannot be written, give the lesson in the reply instead.

Non-negotiable rules

1. Conventions are read, not assumed. Before recommending a shape, find how this API already does it: an existing endpoint, the error helper, the OpenAPI or GraphQL schema, the SDK. Cite the location. A recommendation that ignores the house convention is a new inconsistency, however good it is in the abstract.
2. Deviations are explicit. When the new surface must differ, write it as a NEW DECISION with its reason. Never introduce a second style quietly.
3. Consumers are evidenced. Claim an external consumer only from evidence: a mobile app in the repository, a published OpenAPI document, versioned routes, API keys, webhook subscriptions, documentation addressed to integrators, a package published to a registry. Otherwise it is an open question.
4. Every change is classified. ADDITIVE: a new optional field, a new endpoint. BEHAVIORAL: the same shape with a different meaning, which is the dangerous one. BREAKING: a field removed, renamed or retyped; a newly required input; tighter validation; a changed status code, ordering or pagination; a changed auth scope. A behavioral change is breaking for every consumer that relied on the old meaning.
5. Irreversible decisions are written down, in the decisions block and, when the project keeps one, in the schema or API documentation in the same change.
6. No best-practice lecture. Every line in the block is a convention followed (with its location), a decision made (with its reason), or a question for a person. Anything else is deleted.
7. Short. The block fits in about ten lines. Detail is available when asked for.

Workflow

1. The surface and its consumers

Name the kind of interface: HTTP, GraphQL, webhook, event, SDK, CLI or file. Name its visibility: public, partner, internal but separately deployed, or internal and same-deploy. Then state the consumer evidence. For same-deploy only, stop here. If the code is shared, Impact Map covers its callers.

2. Harvest the conventions

Find two or three existing interfaces of the same kind, and read off:

• naming and casing, and ID format
• the error envelope and code vocabulary
• pagination style, parameter names and maximum page size
• filtering and sorting syntax
• authentication and scopes
• idempotency header
• versioning scheme
• timestamps and time zones, money representation
• null versus absent, envelopes versus bare arrays
• rate-limit headers
• webhook signing and retry schedule

Each becomes a FOLLOWS line with its location. If nothing comparable exists, say so: this surface sets the convention, and that is itself a decision.

3. Decide what cannot be taken back

references/contract-decisions.md lists the decisions per interface kind, and what goes wrong later when each is left implicit. The ones that come up most:

• Any interface: identifiers, field names, types, nullability, whether an enum is open, machine-readable error codes, default ordering.
• Writes: idempotency and retry safety, concurrency control, partial success in batch operations.
• Lists: page stability under inserts, maximum page size, and whether to return totals, which are expensive to compute and impossible to withdraw.
• Webhooks and events: at-least-once delivery and the event id receivers deduplicate on, ordering, signing with a timestamp and replay window, the retry schedule, payload versioning.

4. Classify a change to an existing contract

Go field by field: ADDITIVE, BEHAVIORAL or BREAKING. A breaking change needs a stated migration path, and references/compatibility.md has the usual ones: add alongside and deprecate, a new version, dual-emit for events, a sunset date. Also say how consumers find out.

5. Write it down, then hand off

Put the decisions block before the work. Update the contract document the repository keeps in the same change. Hand the decisions to proof-driven-dev as contract tests: the shape, error codes, page stability, idempotent retry, and signature verification.

What this skill is not

• Not an API style guide. The house style is whatever this repository already does. The skill enforces consistency with it, not a preference.
• Not a security review. Authorization depth, rate limiting and data exposure belong to Standards Compass. This skill states which principal the contract lets see what, and hands the rest over.
• Not an impact map. It decides what an interface should promise. Impact Map finds who, in this repository, already depends on what it promises now.

References

• references/contract-decisions.md — the decisions per interface kind, and what goes wrong later without them
• references/compatibility.md — additive, behavioral and breaking changes, and migration paths

Worked examples

examples/public-list-endpoint.md — a public list API that follows the house conventions · examples/outgoing-webhook.md — a webhook's delivery contract · examples/breaking-rename.md — a field rename that a separate service consumes · examples/internal-endpoint.md — the endpoint that gets no contract block.