Articles

Beyond Gherkin: ADR, SHALL, OpenAPI, and the rest of the specs pack

Gherkin is only the executable proof layer. SurveyDesk also keeps ADRs, SHALL requirements, OpenAPI, FormSpec, product story, and regeneration prompts — so you do not have to rewatch YouTube to learn the architecture.

5 Oct 202610 min read

ADRSpec-Driven DevelopmentSurveyDeskGherkin

After the 12 September SurveyDesk live build, people often open the get-started article, click Session notes, and only find the latest Saturday notes. Then they ask: where are the explanations of documents besides Gherkin — especially ADRs? Short answer: those docs were never meant to live only on the notes page. They live in the repo under specs/, and this article is the readable map.

12 Sep session notes (article): https://suherman.net/articles/surveydesk-12-sep-session-notes
Repo: https://github.com/iman-suherman/survey-desk — read specs/ before apps/
Recording: https://youtu.be/h3FPQEw2QNI

Gherkin is proof — not the whole contract

In Spec-Driven Development, different files answer different questions. Mixing them is why the demo feels like “only Gherkin exists.”

Product story (specs/product) — who is it for, what is in/out of scope, demo journey.
SHALL requirements (specs/requirements) — durable product rules with IDs (SD-001 … SD-012).
Domain notes (specs/domain) — survey, FormSpec, lifecycle, response, results vocabulary.
OpenAPI (specs/api/openapi.yaml) — HTTP shapes the API must honour (language-neutral).
ADRs (specs/adr) — why we chose this architecture so agents do not “improve” it away.
Gherkin (specs/acceptance) — executable scenarios (Given / When / Then) that prove the SHALL.
Regeneration (specs/regeneration) — prompts so another agent can rebuild apps/ from the contract.

Loading diagram…

Same product story, layered into contracts. Gherkin sits at the proof edge — not alone in the middle.

What an ADR is (and why it is not Gherkin)

An Architecture Decision Record freezes a choice and its consequences. Gherkin freezes a behaviour you can test. If you only have Gherkin, an agent can still “helpfully” move you to Postgres in the cloud because no scenario said “must stay on one SQLite file.” The ADR says that out loud.

SurveyDesk ADR tour (read these first)

Open https://github.com/iman-suherman/survey-desk/tree/main/specs/adr. Start with these ten — each is short on purpose.

ADR-001 Monorepo — one checkout for API, web, iOS, Android so a one-hour live build stays possible.
ADR-002 SQLite — local file persistence; wipe/reset without cloud credentials.
ADR-003 Anonymous public — respondents need no login; soft abuse controls only.
ADR-004 Mobile owns operators — phone/tablet is the desk; browser is the audience.
ADR-005 FormSpec JSON — forms are data shared by mobile builder and web renderer.
ADR-006 English naming — one product name across specs, packages, and GitHub.
ADR-007 Native mobile — Swift/SwiftUI and Kotlin/Compose; Expo out of scope for v1 operators.
ADR-008 Brand theme — shared colour tokens and logo assets across all surfaces.
ADR-009 Android build speed — keep Wave-1 regeneration inside the same budget as iOS.
ADR-010 Language-neutral API — OpenAPI + SQLite is the contract; Python is the reference, Java welcome.

markdown

# ADR-002 SQLite for persistence

## Decision
Use a single local SQLite database file for surveys and responses.

## Why
Matches “still running locally”, easy wipe/reset, no cloud credentials.

## Consequences
Not a multi-region SaaS store. Backup = copy the file.

That shape — Decision / Why / Consequences — is the whole ADR habit. Keep it boring. Agents hallucinate less when the boring file exists.

SHALL vs Gherkin (same truth, different jobs)

A SHALL is the rule humans and agents argue about. Gherkin is the scenario that proves the rule still holds after someone regenerates apps/.

text

# From specs/requirements (illustrative)
SD-003: submit SHALL be rejected when the survey is closed.

# From specs/acceptance/lifecycle.feature
Scenario: Reject responses when closed
  Given a survey with status "closed"
  When a respondent submits answers to its public slug
  Then the API rejects the submission

OpenAPI and FormSpec — contracts that are not scenarios

openapi.yaml — paths, status codes, payloads. Implement in Python, Java, Go… as long as the shapes match.
FormSpec — JSON field types (short_text, rating_1_5, …) shared by iOS/Android builders and the Next.js renderer.

A 20-minute reading order (no YouTube required)

This article — so the map is in your head.
12 Sep session notes article — what we actually covered live.
specs/product/vision.md + demo journey — the story.
specs/adr/ADR-002, ADR-005, ADR-007, ADR-010 — the architecture spine.
One SHALL (e.g. SD-003) + its Gherkin in lifecycle.feature.
Only then open apps/ — or ask an agent to implement one ID.