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.
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.
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 /api-design-review only if at least one of these is true:
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.
Produce a lightweight design review that answers:
Summarize the proposed API work in a few lines:
If the work is not actually API-shaping, stop and return control to the caller.
Capture these before judging the design:
If these are missing, ask the caller to supply them or derive them from the existing pitch/research context before proceeding.
Evaluate the proposal across these dimensions:
Prefer additive change over mutation of existing behavior. If a contract must evolve incompatibly, say so explicitly.
Return a short memo with these sections:
List the contract decisions that must be fixed before implementation starts.
State one of:
Explain why.
List the 2-5 highest-risk failure modes.
Give the simplest viable recommendation that fits the constraints.
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.
/research or /write-a-prd/research or /write-a-prd, then onward through the normal pipeline