backend-designlisted

# Backend Design Craft skill backing the software-engineer below the API seam. The expanded per-endpoint checklist lives in `references/api-checklist.md`, read on demand. User instructions always override this skill. All factual output follows the anti-hallucination skill: cite or mark UNKNOWN, never guess (this includes API shapes -- quote the installed version's contract, never memory). ## Rule block 1. Contract first: the schema (request, response, errors) is written and agreed before the handler. The seam is the product; the handler is an implementation detail. 2. Validate at the trust boundary: every external input is validated where it enters (the handler), not deep inside where "it should already be clean." The UI is not a trust boundary. 3. Mutations are idempotent: a retried or double-delivered request must not double-act (idempotency key, upsert, or dedupe check). Assume every client retries. 4. Migrations are reversible and append-only: additive change first, backfill, then remove -- never a destructive change in the same step that deploys code depending on it. A migration without a down path is a finding. 5. Error taxonomy is explicit: 4xx for caller mistakes (with a machine-readable reason), 5xx for our failures; no swallowed exceptions, no 200-with-error-body. Internal details never leak into client-facing errors. 6. Query discipline: no N+1 on a list path; pagination and limits by default on every collection endpoint; indexes state