Immutable. This exact content is served forever at /api/v1/blob/bdb05e884c7811d1.
--- name: api-design-review description: "Invoked helper skill for higher-risk API contract decisions, usually called from /research or /write-a-prd. Use when the unresolved question is API shape, compatibility, auth, webhook design, or paradigm choice. Not a default top-level workflow step or a substitute for ordinary implementation work." --- # API Design Review Use this skill when API complexity is high enough that the normal `/research` or `/write-a-prd` flow needs a focused contract review. This is an invoked skill, not a default pipeline step. It exists to add rigor only when the cost of an API mistake is unusually high. ## Invocation Position This is an invoked helper skill. It normally runs from `/research` or `/write-a-prd` rather than as the first entry point for a feature. Use it when the unresolved question is the API contract itself: paradigm choice, consumer-facing shape, compatibility posture, or auth and webhook model. Do not use it for ordinary backend implementation work or for non-API module design questions that belong in `/design-an-interface`. ## Invoke This Skill When Invoke `/api-design-review` only if at least one of these is true: - a new external or partner-facing API is being introduced - an existing request or response contract is changing - OAuth, scopes, token model, or webhook verification is involved - there is real uncertainty about paradigm selection (REST, RPC, GraphQL, WebHooks, WebSockets) You may also invoke it for internal APIs with multiple independent consumers when a contract mistake would create broad cleanup cost. Do not invoke it for ordinary backend changes that merely happen to call an API without changing the contract shape. ## Goals Produce a lightweight design review that answers: - What developer problem is this API solving? - Who are the consumers and what operations do they need? - What paradigm best fits the operation inventory? - What is the minimum viable auth and scope design? - Is the proposed change additive or breaking? - What contract details must be fixed before implementation starts? ## Workflow ### 1. Establish the API surface under review Summarize the proposed API work in a few lines: - new API vs change to existing API - internal vs external consumers - synchronous request/response vs event/webhook delivery - auth model involved - known compatibility constraints If the work is not actually API-shaping, stop and return control to the caller. ### 2. Write the minimum spec-first inputs Capture these before judging the design: - **Problem statement** — what developer pain or capability gap exists? - **Impact statement** — what outcome does solving it enable? - **Developer consumers** — who integrates with this and what do they care about? - **Operation inventory** — list the concrete operations the API must support If these are missing, ask the caller to supply them or derive them from the existing pitch/research context before proceeding. ### 3. Review the design Evaluate the proposal across these dimensions: - **Paradigm fit** — does REST/RPC/GraphQL/WebHooks match the operation inventory? - **Contract shape** — are inputs, outputs, required/optional fields, and defaults explicit? - **Error design** — are there machine-readable codes plus human-readable messages? - **Security model** — are scopes, token handling, or webhook verification conservative and clear? - **Compatibility** — is the change additive, or does it risk breaking existing consumers? - **Rejected alternatives** — what was considered and why was it rejected? Prefer additive change over mutation of existing behavior. If a contract must evolve incompatibly, say so explicitly. ### 4. Produce the review result Return a short memo with these sections: #### API Design Verdict - **Proceed** — the contract is shaped enough to enter implementation - **Proceed with constraints** — acceptable, but only if listed constraints are preserved - **Revise before implementation** — unresolved design issues remain #### Must-lock decisions List the contract decisions that must be fixed before implementation starts. #### Compatibility classification State one of: - **Additive** - **Potentially breaking** - **Breaking** Explain why. #### Key risks List the 2-5 highest-risk failure modes. #### Recommendation Give the simplest viable recommendation that fits the constraints. ## Output guidance Keep the output concise. This is a focused design review, not a full PRD or a full research report. Good outputs help `/research` or `/write-a-prd` sharpen the contract before implementation. Bad outputs restate generic API best practices without deciding anything. ## Handoff - **Expected input:** API-shaped uncertainty from `/research` or `/write-a-prd` - **Produces:** a concise verdict, compatibility classification, must-lock decisions, and key risks - **Returns control to:** the calling skill so shaping can continue with a firmer contract - **Typical next step:** back to `/research` or `/write-a-prd`, then onward through the normal pipeline