Spec-First Build - Session Folder
The Build session of Innovation Day. A full product team uses AI to ship a real API endpoint the right way round: spec first, code second. The win condition isn’t “it works” - it’s “we agreed what good looked like before we generated it, and a human signed every step.” That’s the five ways of working made hands-on.
The other half of the day is the Build-a-Skill session - same five ways, non-technical audience, no code. Both pull their wording from the single source of truth:
ways-of-working.md.
Who it’s for
The whole product team, all five roles in the room at once. Nobody sits this out - spec-first is a team sport, and the spec is where the roles meet.
| Role | What they own in the spec-first flow |
|---|---|
| Product | The product spec: rules, acceptance criteria, what “good” means for /recommend. |
| Architecture | The contract shape + one ADR capturing a real trade-off (the why). |
| Dev | Stub + failing test, then implement to the frozen contract - in small steps. |
| QA | Tests at the lowest viable layer; contract test that the response matches the spec. |
| UI/UX | The states the data must support - loading, empty, populated, the N/A dimensions. |
Mixed confidence is fine. The contract is the shared artifact that lets a PM and a dev argue about the same thing.
The arc
The session is tool-agnostic - any AI assistant, any of the three substrates below. The shape is the same everywhere.
| Phase | What happens | Anchor |
|---|---|---|
| Brief | The /recommend endpoint returns 501. Here are the product rules. Do not write feature code yet. | Way #1 |
| Gate 1 - freeze the contract | The team authors the /recommend 200 response schema in openapi.yaml, using the fully-specified /compare as the worked example. Schema frozen before any implementation. | REQ-API-2, Way #1 |
| Stub + failing test | Dev/QA write a contract test against the frozen schema. It fails - there’s no implementation yet. | QTEST-EARLY, Way #4 |
| Implement in small steps | Build to the contract, one reviewable increment at a time, AI assisting. | ENG-PRIN-INCR-STMT, Way #4 |
| Human review gate | Another human approves. No self-merge - the AI may assist the review, a person signs it. | ENG-PRIN-REVIEW-STMT, Way #2 |
| ADR | One page (often one line): the trade-off you made and why. Keep it simple. | ENG-PRIN-DOC-STMT, Way #5 |
| Debrief | The standards pub quiz names what they just did; the commitment card carries it to Monday. | - |
Why /recommend and not /compare: /compare is fully specified in the contract on purpose - it’s the worked example teams read to learn the shape. /recommend is deliberately partial (a TODO in the spec) so the team has to do the spec-first work for real. See the comments in openapi.yaml.
Three substrate options
Pick one based on the room. The teaching beats are identical - only the surface changes.
| Option | Best for | Substrate |
|---|---|---|
| A - Live in RISE Mini | A team that can run the app. The richest version. | Implement /recommend in a stack (Next.js or Spring Boot), test against the running server, demo it live. |
| B - Contract-only | Mixed-confidence rooms, or no working installs. | Author the OpenAPI schema and a contract test by hand. No server needed - the deliverable is the frozen, reviewed spec. |
| C - Bring-your-own task | An intact team with a real backlog item. | Apply the same flow (spec → stub → test → implement → review → ADR) to one of their endpoints. Highest transfer to Monday. |
Default to A if installs are verified, B if the room is non-technical or the network is shaky, C if you’ve got an intact team that wants to leave with real work moved forward.
What’s in this folder
| File | Purpose |
|---|---|
README.md | This index. |
standards-pub-quiz.md | 7-question Mentimeter round on the standards the team just used. Run it right after the build. |
monday-commitment-card.md | Fill-in card: the one place I’ll spec before I code this week, the standard I’ll adopt, my buddy, my check-in date. |
Canonical sources this session leans on (read, don’t restate):
../ways-of-working.md- the five ways. Single source of truth.../../../stacks/nextjs/openapi.yaml- the machine-readable contract./comparefull,/recommendpartial.../../../API-CONTRACT.md- the canonical endpoint rules (the/recommendlogic teams spec against).../corporate-standards-main/- the real cite IDs (REQ-API-, QTEST-, ENG-PRIN-, QUAL-PRINC-).
How to run it
- Before the room: verify your chosen substrate. For A, confirm at least one stack runs (
/recommendshould return 501 - that’s correct, it’s the gap). For B/C, no setup beyond the contract file. - Brief the gap, hold the line: show that
/recommendreturns 501 and read the product rules. Then the hard rule - no feature code until the contract is frozen. This is the whole session; protect it. - Run Gate 1: teams author the
/recommendschema from the spec, using/compareas the model. Don’t move on until a schema is frozen. - Build small, review human: stub + failing test, then implement in increments, then a human approval. Spot the techniques as you roam.
- Land the ADR: one line is enough. The point is the why.
- Debrief: run the pub quiz, then hand out the commitment card. Calendar invites before anyone leaves.
For timing, scoring, sabotage cards, and troubleshooting, use the existing facilitator guide - it covers the Build session’s mechanics and stack differences.
Where openapi.yaml lives in each stack
The contract is the same file, served identically by both stacks (REQ-API-2 - one machine-readable spec, kept in sync).
| Stack | Path | Runs on |
|---|---|---|
| Next.js | stacks/nextjs/openapi.yaml - endpoint at src/app/api/recommend/route.ts | :3099 |
| Spring Boot | stacks/spring-boot/ (same contract; RecommendController.java) | :8080 + :3099 |
If you only have time to look at one file before the session, make it stacks/nextjs/openapi.yaml - the inline comments are the lesson plan.
Pointers
- Parallel session: Build-a-Skill - the non-technical track, same five ways, using the SKILL one-pager template.
- The five ways of working:
../ways-of-working.md. - Top-level workshop guide:
../../../README.mdand the participant site atsite/index.html. - Mechanics (timing, scoring, troubleshooting):
../../facilitator-guide.md.
Built at Innovation Day. The five ways of working: ways-of-working.md.