Clinic Booking, from idea to proof
One small solution followed from the first request to a change after launch, so you can see where every concept fits and what the agent receives at each step.
The idea
A group of three clinics loses time on the phone. Patients call to book, to move and to cancel; receptionists spend mornings on it; one appointment in eight is a no-show. The owner, Aylin, wants patients to do this online and asks a coding agent to help build it.
A vibe-coding session could start with "build me a booking site" and have something on screen in an hour. What follows is what it takes for that something to be the right thing, and to stay right as the solution changes.
0. The request: a demand and an initiative
Aylin's request is recorded as a demand: who asked, how, when and what. It lands in the Funnel of the Portfolio board. She reviews it and answers it with an initiative, "Online booking — first release", managed as a project. Everything below — objectives, requirements, work — belongs to that initiative.
Clinic Booking itself is the solution: the system that will outlive this first release. It starts with one component, the web app, whose code lives in one repository on GitHub (GitLab works the same way). What the solution does will be kept in its design records; for now there are none, because nothing is built yet.
1. Why: objectives
The first question is not what to build but what must be true when it works. Aylin and the agent agree two measurable objectives:
| Code | Objective |
|---|---|
| OBJ | Patients can book, move or cancel online in under a minute. |
| OBJ | Halve no-shows within six months. |
Everything below will trace back to one of these. When someone later asks for a loyalty programme, the first question is which objective it serves.
2. What: requirements, from need to behaviour
| Level | Record | Refines |
|---|---|---|
| Business | BR — Patients can book outside opening hours. | the first objective |
| Stakeholder | SR — As a patient, I can move my own appointment. | the BR |
| Stakeholder | SR — As a receptionist, I see every change made overnight when my shift starts. | the BR |
| Functional | FR — A patient can move an appointment up to 2 hours before it starts. | the patient SR |
| Functional | FR — Send a reminder 24 hours before each appointment. | the no-show objective, via its BR |
| Non-functional | NFR — The booking page loads in under one second on a mid-range phone. | the patient SR |
| Technical | TR — Use the clinics' existing calendar; keep no second schedule. | realizes the FRs |
Each requirement gets acceptance criteria before it is approved. The "move up to 2 hours" requirement gets three: the allowed move, the refused late move, and a slot that is already taken.
3. Limits: constraints
| Type | Constraint | Applies to |
|---|---|---|
| Product | Web only in the first release, no native apps. | the whole solution |
| Business | Patient data stays in the EU. | the whole solution |
| Project | Live within three months, before the spring rush. | the whole solution |
Because these apply to the whole solution, the agent receives them with every piece of work. When it later reaches for a US-hosted SMS service for reminders, the business constraint stops it.
4. What else the initiative delivers
The software is not the whole job. A project requirement of the initiative says every receptionist is trained on the new schedule view before go-live. A work package, "Release 1 — spring launch", with an owner, dates and a budget, delivers it together with the software.
5. Work: from theme to story
| Level | Item |
|---|---|
| Theme | Self-service for patients |
| Epic | Online rescheduling (implements the patient SR) |
| Story | Move an appointment from the confirmation e-mail link (implements the FR, covers its three criteria) |
| Story | Show free slots for the next two weeks |
| Task | Grant the booking service access to the clinics' calendar (needs IT approval) |
A story is ready only when it implements an approved requirement and covers at least one criterion, and it can be committed because its initiative answers Aylin's demand. That is what lets the agent work on it without a meeting.
Each story also says what it will change in the solution's design. The e-mail-link story carries a design change: add a functional design record, "Move an appointment", with the 2-hour rule.
6. Building: what the agent receives
When the agent picks up the e-mail-link story, it does not get a pile of documents. It gets a work context for that one story:
- the requirement it implements, and the chain above it up to the objective;
- the three acceptance criteria it must prove;
- the constraints that apply (web only, EU data, three months);
- the technical requirement and the decision behind it (use the calendar API directly, not a nightly sync);
- the solution's current design it must respect, and the design change this story makes to it;
- and, read alongside, the account's standards, such as logging every read of patient data.
While building, the agent notices the calendar API may throttle requests on busy Monday mornings. It raises a risk instead of mentioning it in passing. It is unsure whether parents may move their children's appointments, so it opens a question with a working assumption: only your own, for now.
7. Proof: criteria and tests
The agent writes an end-to-end test for each criterion and links it. CI runs them; the results, not the agent's summary, turn the criteria Met. The story moves through code review and verification, and a person moves it to Done. Only then is its design change applied: the solution now has a design record "Move an appointment", version 1, which records the story, requirement and initiative that brought it.
After launch a tester finds that a move 1 hour 59 minutes before the appointment is accepted. Because the criterion says it must be refused, this is a defect, not a debate. Reported on its own, it goes to the solution's quarterly maintenance initiative. It is fixed and closed with a test that proves the fix.
When all its work is Done, the first-release initiative closes, and Aylin's demand with it. Its requirements become history — kept with their reasons, no longer binding — and the design records now describe what was built.
8. Change: the rule moves from 2 hours to 4
Receptionists say two hours is too short to refill a slot. In a folder of documents this is where solutions go wrong: the old rule survives in a spec, a ticket and a prompt, and the agent keeps following it.
Here the request is a new demand. Aylin answers it with a small-work initiative, "Four-hour notice". Its functional requirement says moves must be made at least 4 hours before, with its own criteria. The story that implements it carries a design change to "Move an appointment": 2 hours becomes 4.
While the work runs, the agent sees both: today's design (2 hours), which is still what the system does, and the change it must make (4 hours). The tests are updated to prove the new criteria. When the story is Done, the change is applied and the design record gets version 2. From then on every agent reads 4 hours as the truth; the 2-hour rule is history, kept with its reasons.
The team also records a lesson from the defect: calendar times are local clinic time, not UTC, so convert at the boundary. The next agent session starts with it.
What this story shows
- A demand and an initiative gave every change a requester, a scope and an end.
- Objectives kept the scope honest.
- The chain of requirements told the agent why, not just what.
- Constraints stopped good-looking shortcuts.
- Criteria and tests made "done" provable, and a defect undeniable.
- Risks, questions and lessons kept what the agent noticed where people decide.
- Design records described what the system does today, and changed only when the work that changed them was Done.
- An explicit change meant the agent stopped following the old rule the moment the new one was delivered.