Write Comprehensive Integration Specifications

Writes comprehensive integration specifications that serve as definitive contracts between systems, APIs, and services - detailed technical documentation covering authentication, endpoint contracts, data models, error handling, rate limiting, sequence diagrams, and test scenarios, aimed at eliminating ambiguity in system integrations.

Use this skill when documenting a new API integration, defining a contract between two services, specifying authentication flows and endpoint behavior before implementation, or writing test scenarios that a partner team needs to validate against. Not a fit for writing the integration code itself or for informal internal notes that do not need to serve as a binding contract between teams.

Every integration spec produced covers eight essential components: integration overview (purpose, scope, high-level architecture), authentication and authorization (security mechanisms, token handling), endpoint definitions (complete API contract with request/response schemas), data models, error handling (codes and recovery procedures), rate limiting (throttling rules and quota management), sequence diagrams (visual interaction flows), and testing scenarios (integration test cases and validation criteria).

Authentication is specified with complete, runnable examples - for instance a Bearer Token / OAuth 2.0 client credentials flow with a token endpoint, required headers, and automatic token refresh threshold defined in YAML.

Endpoints are documented to full technical detail: HTTP method and path, request body schema with field types and constraints (required/optional, max length, numeric ranges, format patterns), and success response bodies with concrete example values (order IDs, status, tracking URLs).

Error handling specs define each error code with its HTTP status, message, retry strategy (e.g. exponential backoff vs. do-not-retry), and resolution guidance, plus the exact response headers returned (Retry-After, X-RateLimit-Reset). Rate limiting sections define per-endpoint and global request limits, burst allowance, and the rate-limit headers returned on every response. Sequence diagrams use Mermaid syntax to show multi-service interaction flows (client, API gateway, order/payment/inventory services). Test scenario sections specify preconditions and expected outcomes for both happy-path and error scenarios (e.g. insufficient inventory), and environment configuration sections define sandbox vs. production base URLs, SLAs, and maintenance windows.

Produces specs in the formats integration engineers already use for the contract itself - YAML for configuration and auth, JSON for schemas and error codes, HTTP-style request/response blocks for endpoints, and Mermaid for sequence diagrams - rather than a single fixed document format.

Engineers and technical writers who need to produce a definitive, unambiguous contract between systems before or during integration work - useful when a partner team needs a complete reference covering authentication, every endpoint's request/response shape, error codes with retry guidance, rate limits, and test scenarios, rather than a scoped implementation guide.