Lab 4: From Requirements to Spec to Build¶

What you will learn¶

• How to turn requirements into user stories with acceptance criteria that an agent can be checked against
• How to model a process flow, including what happens off the happy path
• How to explore several designs cheaply before committing to one
• How to write a spec, build from it in plan mode, and run a five-minute usability test

This lab uses your own project. Have discovery/requirements.md from Lab 3 open.

Part A: User stories and acceptance criteria (15 minutes)¶

Pick the two or three Must requirements at the center of your MVP. For each, write a user story with acceptance criteria in specs/user-stories.md. Give each story an ID and cite the requirement it comes from.

### S1 (FR-1): Record a payment
As a **club treasurer**, I want **to mark a member as paid from the member list**
so that **I can see who still owes without opening a spreadsheet**.

Acceptance criteria:
- WHEN the treasurer clicks "Mark paid" on a member THE SYSTEM SHALL record the
  date and amount and show the member as Paid.
- WHEN the amount is empty or not a number THE SYSTEM SHALL keep the member unpaid
  and show "Enter an amount, like 25".
- IF the member is already paid THE SYSTEM SHALL show "Paid on <date>" instead of
  the button.

The criteria above use the EARS pattern from Specs. Each one is a sentence you can test with a yes or no. Write at least one criterion per story for something going wrong.

Part B: Model the process flow (10 minutes)¶

Draw the flow for your most important story as a Mermaid flowchart in design/flow.md, following Flows Before Screens. Include every decision point and every error or empty state, not just the happy path.

```mermaid
flowchart TD
  A[Treasurer opens member list] --> B{Any members?}
  B -- No --> C[Empty state: Import members from CSV]
  B -- Yes --> D[List shows Paid and Unpaid]
  D --> E[Click Mark paid]
  E --> F[Enter amount]
  F --> G{Valid amount?}
  G -- No --> H[Error: Enter an amount, like 25] --> F
  G -- Yes --> I[Save payment] --> J[Member shows Paid on date]
```

If more than one person or system is involved (for example a treasurer and a club president), add a subgraph for each role to make a swimlane diagram.

Part C: Diverge, then converge (10 minutes)¶

Before building anything, ask Claude for alternatives, following The Design Process:

Read discovery/requirements.md, specs/user-stories.md, and design/flow.md.
Before you build anything, make three different throwaway mockups of the main
screen as three separate static HTML files in design/mockups/. Make them differ in
layout and flow, not just colors. Use realistic sample data, not lorem ipsum.
Under each, write two sentences on what it assumes about the user. Do not write
any app code yet.

Open all three in a browser. Pick one, or combine parts, and write why in design/decision.md. Check your choice against two of Nielsen's ten heuristics.

Part D: Write the spec (10 minutes)¶

Create specs/v1-spec.md using the spec layout from Specs:

# <System name> v1, spec

## Intent
<One paragraph: who this is for and what job it does. Link discovery/requirements.md.>

## Stories and acceptance criteria
<Link or paste S1 to S3 from specs/user-stories.md.>

## Screens and flow
<Link design/flow.md and the chosen mockup.>

## Data
<The things the system stores and their fields. For v1 this can live in the browser;
a real database comes in Lab 6.>

## Decisions already made
- Stack: Next.js (TypeScript) with Tailwind, deployed to Vercel.
- <anything else you decided, and why>

## Considered and rejected
<What you chose not to do, and why.>

## Out of scope for v1
<From the MVP scope in your requirements.>

## Open questions
<What you still do not know.>

Part E: Build from the spec (in class and after)¶

Create your app in the app/ folder of your course repo. Start Claude Code in your course repo, switch to plan mode (Shift+Tab), and paste:

Read specs/v1-spec.md and everything it links to. Plan how to build v1 as a
Next.js app with TypeScript and Tailwind in the app/ folder. Break the work into
small tasks of 10 to 30 minutes, each one naming the story and acceptance criteria
it satisfies. Do not write code until I approve the plan.

Approve the plan when it is right. Then build one task at a time: after each, run the app (npm run dev in app/, then open the address it prints), check the acceptance criteria for that task yourself, and commit. Keep a checklist in specs/v1-tasks.md.

When the stories work, deploy: import your course repo into Vercel again as a new project with Root Directory app. Put the live URL in your README under Where the work lives.

Part F: Five-minute usability test (before Tuesday)¶

Ask one person who has not seen your system (a classmate, roommate, or your real user) to do the main task while thinking out loud. Give them the task, not instructions: "You just collected dues from three people. Record them." Then say nothing. Follow Running a Usability Test.

Record in design/usability-test-1.md: where they hesitated, what they said, what they clicked that did nothing, and whether they finished. List the top two changes you will make, and make at least one.

Reflection¶

Write labs/lab-04/reflection.md:

1. Which acceptance criterion caught something the agent's own report said was done?
2. What did the three mockups show you that you would not have thought of with one?
3. What did the usability test reveal that you could not see yourself? What did you change?

Turn in¶

Submit the link to your course repo on Canvas. It should contain:

• specs/user-stories.md, specs/v1-spec.md, specs/v1-tasks.md
• design/flow.md, design/mockups/ (three files), design/decision.md, design/usability-test-1.md
• Your v1 app in app/, deployed, with the URL in your README
• labs/lab-04/reflection.md

These are also most of your Sprint 1 output, due Mon, Nov 23.

How larger systems do this¶

Large organizations formalize each step you took today. Requirements become a product requirements document or a software requirements specification reviewed and signed off by stakeholders. Process flows become BPMN models or UML activity and sequence diagrams. Mockups go through a design system with shared components, and usability testing is run by a research team on a schedule. Each artifact exists for the same reason yours does: so that someone who was not in the room, a new engineer or an agent, can build the right thing and check that they did.