gilde

← All craftbooks

API Contract Review

Review and QAevalv1.1.3released 2026-09-01workflow: build-loop

Review an API contract or specification (OpenAPI/REST/GraphQL) for correctness, consistency, and developer ergonomics, then produce a findings report. First scopes the surface and locks an API design checklist (resource naming and HTTP semantics, status codes, pagination and filtering, error schema consistency, auth, versioning and backward compatibility, idempotency, and schema/type rigor), then reviews each endpoint and type against those rules and REST/GraphQL best practices, then writes a findings report rating each issue and giving the corrected contract snippet. Use this for an API design review, reviewing an OpenAPI/Swagger spec, a REST or GraphQL contract review, endpoint/schema critique, or checking an API for consistency and backward compatibility before it ships — it returns specific, spec-anchored fixes rather than 'make the API cleaner'.

Steps

Entry step: scope. Each step names the specialist role it wants; the full working prompt is expandable.

  1. Scope the contract reviewreviewerentry

    map the surface, lock an API design checklist

    Show working prompt
    Step 1: Read the contract (OpenAPI/Swagger YAML/JSON, a GraphQL SDL, or the route/handler definitions) and inventory every endpoint/operation/type with its method, path, params, request/response schema, and auth. Step 2: Note whether this is a NEW API or a CHANGE to an existing one (if a change, backward compatibility is a first-class criterion). Step 3: Write an API acceptance-criteria checklist covering: resource naming (nouns, plural collections, consistent casing) and correct HTTP-method semantics; correct and consistent status codes (201 on create, 204 on empty, 4xx vs 5xx); a single consistent error schema across all endpoints; pagination/filtering/sorting conventions applied uniformly; auth declared per operation; explicit versioning and no breaking changes (no removed/renamed fields, no narrowed types, no new required inputs) for changes; idempotency for unsafe-but-retried operations; and schema rigor (required vs optional correct, enums constrained, types precise, examples present). Step 4: State the pass condition for each. Write the surface inventory + checklist to `write_task_note` AND `{{workPath}}/scope.md`. No findings yet.

The deliverable `{{workPath}}/scope.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.
  2. Review the endpointsdeveloper

    check each operation + type against the rules

    Show working prompt
    Step 1: Walk EACH endpoint/operation against the checklist: verify the method matches the action, the path is a sensible resource, the status codes are correct and complete (including error codes), the request/response schemas are precise, and auth is declared. Step 2: Walk EACH type/schema: required vs optional fields are right, enums and formats constrain values, nullability is intentional, and naming is consistent. Step 3: Cross-cut the whole surface for consistency: do all errors share one schema, is pagination uniform, is casing consistent, are similar resources modeled the same way. Step 4: For a CHANGE, diff against the prior contract and flag every breaking change. Step 5: For each finding capture: the operation/type, the rule violated, the impact on a client developer, severity, and the CORRECTED snippet (the fixed YAML/SDL/schema fragment). Good looks like: a finding with a before/after contract snippet, not 'improve error handling'. Stage findings to `write_task_note`. Do not write the report yet.

The deliverable `{{workPath}}/review.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.
  3. Write the contract reportreviewer

    findings with corrected snippets + compat verdict

    Show working prompt
    Step 1: Open `{{workPath}}/api-review.md` and write a verdict: Approve / Approve-with-changes / Request-changes, and for a change an explicit Backward-compatible: yes/no. Step 2: Add a '## Breaking changes' section first if any (each with the operation and the corrected approach), then '## Blocking' and '## Non-blocking' findings, each as `operation/type — rule — impact — corrected snippet`. Step 3: Add a '## Consistency' section for cross-cutting issues (error schema, pagination, casing). Step 4: Add a '## Strengths' note on what the contract gets right. Every finding must cite the operation/type and include a concrete corrected snippet — no generic advice. On a loop-back, fix only the named gaps. `write_task_note` the report path, the compatibility verdict, and the count of blocking findings.

The deliverable `{{workPath}}/api-review.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.
  4. Evaluatereviewer

    Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

    Show working prompt
    Open `{{workPath}}/api-review.md` and grade it against the scope checklist. Check EACH criterion and write PASS/FAIL with a one-line reason: (1) every endpoint/operation and type was reviewed; (2) HTTP-method/status-code semantics were checked; (3) error schema, pagination, and naming consistency were assessed across the surface; (4) for a change, backward compatibility is explicitly stated and any breaking change is flagged; (5) each finding includes a concrete corrected contract snippet; (6) findings are prioritized (breaking/blocking/non-blocking); (7) the verdict matches the findings. If any criterion fails, name the exact gap and loop back.

The deliverable lives in the project's artifacts drawer — open `{{workPath}}/api-review.md` with `read_artifact`, not `read_file`.

Then route — this is the whole point of the loop:

- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "report" })` to loop back. The builder fixes exactly those gaps.

Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.
  5. Finishdeveloper

    All acceptance criteria met. Stamp a short summary and report DONE.

    Show working prompt
    Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

Source

View this craftbook on GitHub · MIT license