IDST
Course contents

Session 4 of 8

Session 4: Waterfall Begins: The Business Case & the Spec

Homework asked what you couldn't build slice-by-slice. In this session you find out, because project three, the capstone, is real, multi-platform software: an iPhone app on your actual phone, a web page in any browser, and one shared database underneath them both. Add a yoghurt in the kitchen; see it from anywhere. Three tech stacks, one product. And we're building it the oldest way in the industry, decide everything first, then build. It's called waterfall, and doing it once, properly, will teach you more about software than a year of one-shots.

Part 1: The complexity cliff (~15 min)

Look back at your wrongs lists from both projects so far. Nearly every item is one of:

At one-page scale you absorb these with quick fixes. Agile absorbs them a slice at a time, learn, reorder the backlog, ship again. But as a project grows, the guesses compound, a wrong guess in the foundations gets built on top of, and when three platforms share one database, a wrong guess in that database is built on top of three times. That's the cliff. Process is how you don't drive off it.

You've now seen the industry's three broad answers, the full comparison is the lifecycle cheatsheet:

And here it is, whole, the whole build on one page. Don't study it in this session; just see the shape: everything above the red baseline is deciding (in this stretch), everything below it is building and proving (Sessions 6–8). Come back to it as each phase becomes yours:

The waterfall lifecycle across Sessions 4–8: business case, specification, four stage gates, design studio, roadmaps, the frozen baseline, two fenced builds, the test and security gates, ship and closure, handover, hardening, retro, with the gstack skills and documents at each phase

Blue = gstack commands · yellow = documents · grey = things you do · red = the frozen baseline everything downstream builds from.

The mindset shift your tutor will bang on about, because it's his day job: the agent is a brilliant, tireless junior developer. Talent isn't its missing ingredient, direction is. Process is how you direct it. Your job is quietly becoming "product owner and reviewer": deciding what to build and judging whether it's right.

Part 2: The business case (~20 min)

Before a professional project gets weeks of anyone's time, someone asks the brutal question: is this worth building at all? That question has a formal home, the business case, and yours gets interrogated in this session. Run:

/office-hours

and pitch the capstone to it, it plays a startup investor, and a good one: it will push on who this is for, why a phone app and a web page, what the smallest version that's still the product is, and what would make you abandon it. The project: Shelf Life, a fridge-and-cupboard expiry tracker. Add an item and its expiry date; see everything sorted by days remaining, colour-coded green/amber/red; a notification the day before something turns; and the whole household able to see (and eat down) the amber list from any browser. Never bin another unopened yoghurt.

Ten minutes in you'll notice something: its questions are the /spec interview from Session 2 wearing a different hat. Requirements interrogation is one skill; only the costume changes. Survive the questioning and you have what the trade calls an approved business case, the licence to spend the three build sessions.

Part 3: Project initiation (~15 min)

Ask Claude to create the project folder and git repo. Then the project's first document, written by hand, by you: CLAUDE.md, the file the agent reads at the start of every session. Standing instructions, so you stop repeating yourself.

The trap: because it's always loaded, every line costs tokens in every session, and a bloated CLAUDE.md is noise that drowns your real rules, the agent starts ignoring half of it. The test for every line:

"Would removing this cause the agent to make mistakes?" If no, cut it.

Your tutor will show you his real one, four lines long, after 25 years in software. It doesn't explain things; it points to where things are explained. Index, not archive. Write yours from the template: under 10 lines, every line passes the test.

Part 4: /spec: decide everything (~60 min)

The heart of the session. In waterfall, the specification is the project: everything downstream, the plans, the build, the tests, the sign-offs, flows from what you decide now. Run:

/spec I want to build Shelf Life: an iPhone app that tracks food expiry dates, a companion web page, and a shared database between them…

It runs five phases and it will interview you, one question at a time, pushing on exactly the gaps you'd otherwise leave for the agent to guess into. Every question it asks is a wrong guess prevented. You've specced before, but on Session 2 you specced a slice in five minutes. In this session you spec a system, and feel the difference. Notice how many decisions a "simple" product contains: What happens to expired items, deleted, archived, shown crossed-out? Can two yoghurts share a name? What time does the notification fire, and does the web page notify, or only the phone?

The decision that towers over the rest: the shared data model. One table, agreed in this session, that the phone app, the web page, and the database all believe in identically, because every platform builds against it, and a change to it later means changing three things that already work. Then the split of labour: what does the app do that the page doesn't (notifications, offline use)? What does the page do that the app doesn't (any browser, no install)? Deciding what each platform doesn't do is as load-bearing as what it does.

Answer honestly, take your time, and use the muscle from Session 2, every answer is an acceptance criterion. The hardest and most valuable answers are the "no"s: no accounts, no barcode scanner, no photos. Good ideas go in the out-of-scope list to wait, not to die. You get exactly one cloud decision, the shared database (it will be Supabase; details when we build it), and everything else stays simple to compensate.

When it's done you'll have a precise, executable spec, the document the rest of the course builds from. Read every line of it. Push back on anything that isn't what you meant. This session is the cheapest anything will ever be to change; from the next session, this document is baselined, changes to it become exceptions, not edits.

Part 5: Close on purpose (~10 min)

Commit the spec and CLAUDE.md. Run /context-save.

Preview of the next session, the final session of the planning half: before a professional project gets money and people, its plan faces gate reviews, executives who each read it through a different lens and can each send it back. The next session your spec faces four of them. You've watched this board at work before, on Session 2, /autoplan convened it automatically for a slice. The next session, for the capstone, you are all four.

What you just learned without noticing

Business-case thinking and requirements engineering, the disciplines that decide whether projects ship or merely continue. The out-of-scope list is the PM skill; "what does done look like?" at system scale is the specification; a data model shared across platforms is the single most common thing real engineering teams argue about; and baselining is how billion-pound programmes keep the ground from moving under the builders.