Naming, error shapes, status codes, and versioning — find the inconsistencies and sequence fixes from non-breaking to breaking.
Free & open · no signup · read-only — it ends by asking · nothing leaves your machine
You are working inside this repo. Mission: review the API as a contract — naming, error shapes, status codes, pagination, versioning — find where it contradicts itself, and sequence the fixes from non-breaking to breaking.
Read-only pass. Your only write is the report file.
Phase 2 sweeps the codebase through every one of these, citing file and line for each finding.
resource nouns, casing, plural/singular, verb leakage in paths; one convention or several?
one envelope shape or many; status codes used correctly (400 vs 422 vs 500); do errors carry actionable detail?
consistent parameters and response metadata across list endpoints?
same mechanism everywhere; any endpoint accidentally weaker?
over-fetching (responses far bigger than any consumer uses) and under-fetching (one screen forced into N calls)
idempotency on retryable operations; partial-failure behavior defined?
strategy for evolving without breaking; undocumented endpoints someone may depend on
One structured report at the repo root — or in reports/, if you keep one — the same shape every time, ready for a teammate — or the optional Studio — to act on.
Every Goal Prompt follows the same four steps, so results are consistent and repeatable — no matter which one you run.
List every endpoint.
Naming — resource nouns, casing, plural/singular, verb leakage in paths.
Every inconsistency names its consumer impact — cosmetic vs correctness.
Create API.md at repo root.
Copy it and paste it into your agent inside the repo you want checked.
Install the goal plugin once — two commands — then just type /goal:api-contract-review.
/plugin marketplace add GhostlyGawd/goal-prompts/plugin install goal@goal-promptsOr install only this Goal Prompt as /goal-api-contract-review:
curl -fsSL https://goal-prompts.vercel.app/install | BRIEF=18 shLet an agent fetch it mid-conversation, or pull the raw Goal Prompt by URL.
https://goal-prompts.vercel.app/raw/18.mdNothing hidden — this is the whole Goal Prompt, verbatim. Read it in a minute, edit it, or copy it as-is.
# Goal: API Contract Review You are working inside this repo. Mission: review the API as a contract — naming, error shapes, status codes, pagination, versioning — find where it contradicts itself, and sequence the fixes from non-breaking to breaking. Read-only pass. Your only write is the report file. ## Phase 1 — Inventory the surface - List every endpoint: method, path, auth requirement, from the actual routes. - Who consumes it: own frontend only, mobile apps, public clients, webhooks? Consumers define breaking-change cost. - Is any of it documented or spec'd (OpenAPI, comments), and does that match the code? ## Phase 2 — Audit through 7 lenses 1. **Naming** — resource nouns, casing, plural/singular, verb leakage in paths; one convention or several? 2. **Error contract** — one envelope shape or many; status codes used correctly (400 vs 422 vs 500); do errors carry actionable detail? 3. **Pagination, filtering, sorting** — consistent parameters and response metadata across list endpoints? 4. **Auth consistency** — same mechanism everywhere; any endpoint accidentally weaker? 5. **Payload discipline** — over-fetching (responses far bigger than any consumer uses) and under-fetching (one screen forced into N calls) 6. **Mutation safety** — idempotency on retryable operations; partial-failure behavior defined? 7. **Versioning & breakage** — strategy for evolving without breaking; undocumented endpoints someone may depend on ## Phase 3 — Curate - Every inconsistency names its consumer impact — cosmetic vs correctness - Split fixes: non-breaking (additive, internal) vs breaking (needs deprecation path) ## Phase 4 — Report Create `API.md` at repo root: 1. **Surface inventory** — the endpoint table 2. **Inconsistency findings** — each: endpoint(s) · issue · consumer impact · fix 3. **Proposed conventions** — the one-page contract: naming, errors, pagination, versioning 4. **Fix sequence** — non-breaking now; breaking changes with their deprecation path 5. **The worst offender** — one endpoint fully redesigned as the exemplar Start the report with today's date. If `API.md` already exists from a previous run, read it first and lead with what changed since. ## Rules - Consistency beats elegance: converge on what most endpoints already do - Never propose a breaking change without its migration path - No API contracts in this repo? Say so in a one-paragraph null report and stop — a null result is a valid finding. - If a `reports/` directory exists at the repo root, write the report there instead of the root. - Before asking, present the top findings as a ranked list in plain words - Report only — end by asking which fixes to make
reports/ directory exists at the repo root, write the report there instead of the root.Follow the docs literally to find where they lie, then rank the gaps by who gets blocked — and which wrong docs to delete.
Extract every user-facing string; hunt jargon, vague CTAs, and unhelpful errors; rewrite the worst ten before/after.
Can a newcomer explain back what this is, who it's for, and how it works after one screen — or does the curse of knowledge leave them guessing?
Every message the product shows when something goes wrong — whether it says what happened, why, and what to do next, or leaves the user stuck.