Use this skill to review API designs and changes. Do not redesign from scratch unless the requested review scope requires it. Focus on concrete defects, compatibility risks, unclear contracts, and practical fixes.
-
Establish the review baseline.
Identify the reviewed surface, intended users, integration scenarios, A&A model, transport style, local conventions, versioning policy, compatibility promise, and known consumer usage.
-
Check problem fit.
Verify that the API solves the user or developer problem it claims to solve. Flag designs driven by internal entities, database tables, subsystem boundaries, or implementation convenience instead of consumer workflows.
-
Check contract shape.
Review abstraction levels, responsibility boundaries, public entities, fields, methods, events, statuses, examples, and documented behavior. Treat exposed behavior as a product commitment.
-
Check compatibility.
Identify observable behavior from docs, specs, examples, generated clients, SDK behavior, errors, timing, consistency, event order, and real usage. Classify changes by consumer impact, not implementation size.
-
Check distributed behavior.
Review idempotency, retries, draft-commit or operation-resource needs, consistency, pagination, async handling, duplex callbacks, bulk operations, partial success, and recovery after failures.
-
Check errors and recovery.
Verify that errors tell clients whether to retry, wait, refresh state, fix input, reauthorize, ask the user, or fail permanently.
-
Apply transport-specific checks.
Use the HTTP/REST, SDK, or UI component references only when relevant.
-
Produce findings.
Lead with findings ordered by severity and consumer impact. For each finding, state the problem, why it matters, the affected contract surface, and the smallest practical fix.
