Spec‑First vs Demo‑First Decision Grid for Founders

Make the decision with two signals: backend complexity and signalling value. If the core value of the product depends on API behavior, data contracts, or real integrations, favor spec-first. If value is user-facing interaction, layout, or onboarding flow that you can validate by clicking through, favor demo-first.

Translate those signals into simple rules: choose spec-first when more than two third-party integrations, concurrent write consistency, or non-trivial business logic determine correctness. Choose demo-first when early user feedback, market fit, or fundraising narrative are the primary goals and the backend can be mocked or stubbed.

Use this 2x2 mental matrix: X-axis = speed to learn; Y-axis = cost of rework. Demo-first maximizes speed to learn but can create mismatch cost later if the demo implies impossible backend behavior. Spec-first raises initial alignment cost but reduces integration surprises and contractor churn.

Operationalize the matrix: estimate speed-to-learn in days and expected rework cost in contractor hours. If expected rework is less than a single sprint of contractor time (e.g., <40 hours) and you need market feedback now, accept demo-first. If rework is likely to block integrations, choose spec-first.

Template 1 — OpenAPI minimal contract: a single OpenAPI YAML describing the critical endpoints, example payloads, and two acceptance tests (happy path + one failure case). Use a linter (Spectral) and run a mock server (Prism) so frontend contractors can work against a contract. This gives independent parallel workstreams and catches integration mismatches early.

Template 2 — Feature card + acceptance tests: one-page feature card with user story, acceptance criteria expressed as Given/When/Then, and a data model appendix. Pair this with a CI job that runs contract tests against a mock server; that CI becomes the single source of truth for behavior.

Template 3 — API mock bundle: OpenAPI file + Postman/collection export + small seed dataset. Include example curl requests and expected JSON responses so contractors can run end-to-end checks locally without access to your production systems.

Template 1 — Clickable demo (Figma/Framer): a small flow (3–6 screens) that demonstrates core value: onboarding → key action → success state. Mark every interactive element with the expected backend behavior in a single annotation layer so engineers understand which interactions are mocked.

Template 2 — Playbook demo + guardrails: a short script for demo sessions plus a short FAQ that lists known discrepancies between demo and production. Use this when demos will be shown to investors or early adopters — the FAQ prevents overpromising and documents what ‘works’ vs what’s simulated.

Template 3 — Prototype with contract slice: build the clickable UI but attach a single OpenAPI endpoint or mock that represents the most important integration. This hybrid reduces the rework cost if you later switch to spec-first.

Make handoffs a checklist of primitives rather than long narratives. For spec-first work paste: (1) OpenAPI file URL, (2) mock server endpoint, (3) acceptance test names and CI link, (4) example requests/responses, (5) one-sentence non-functional constraints (latency, idempotency). This set allows contractors to run local verification without assuming hidden behavior.

For demo-first handoffs paste: (1) prototype link + flow map, (2) list of mocked interactions with exact payload examples, (3) demo FAQ noting 'simulated' vs 'real' behavior, (4) exportable assets and tokens for a single mocked API. Also include expected deliverables: 'convert screens to React components' or 'implement API client to hit mock endpoints' so billing and estimates are precise.