The spec
Describes what the product does, in plain language, from the user’s point of view. It’s the document an engineer reads to know what they’re building. No business framing, no metrics, no go-to-market — just behavior.
Spec versus PRD
Most teams use the words interchangeably. They shouldn’t. The spec and the PRD are two different documents written for two different reasons:
The PRD (Lesson 05)
Wraps the spec in business context: goals, non-goals, user flows, success metrics. It’s the document a stakeholder reads to know why you’re building it.
Write the spec first. The PRD is a frame; the spec is the painting.
Your starting point: the Must list
One paragraph per Must story
For each Must story you finalized in Lesson 02, write one short paragraph that answers three questions:
Per-story spec template
- What does the user see? The screen, the moment, the visible artifact.
- What does the user do? The clicks, the inputs, the decisions.
- What does the system do? The result — what changes, what gets saved, what happens next.
Two to four sentences total per story. If you need more, the story is too big and probably wants to be two stories.
Write in present tense. “The user sees a list of last month’s expenses, grouped by category.” Not “the user will be able to see…” Future tense smuggles in uncertainty.
Then: the system sketch
The per-story paragraphs describe behavior. The system sketch describes the bones around them — in three short bullet lists:
Data
What objects does the system have to keep track of? List nouns. (Users, sessions, transactions, projects…)
Surfaces
What does the user actually touch? List screens or commands. (Sign-in, dashboard, settings, share-link page…)
Integrations
What does the system depend on? List external services or APIs. (Email provider, payment processor, AI model, analytics…)
Five bullets per list, max. The point is to surface the dependencies you didn’t realize you were taking on. If your “integrations” list has nine entries, your POC just got six weeks longer than you thought.
The integration list is the early-warning system for “this isn’t a one-week build anymore.”
Use Claude to draft the spec
Paste your Must list (above) and your Workshop 1 answers into the prompt below. Claude will draft per-story paragraphs and the three system-sketch lists. Edit ruthlessly — the model will sometimes invent a screen you didn’t intend, or assume an integration you don’t want. That’s good. Catching it now is the whole point.
Operator story · Lesson 3
From Alon’s notebook
The shortest spec Alon ever shipped — two pages — and the longest one he ever regretted. Suggested hook: the moment a 30-page spec became the bottleneck, and the rule he’s used since (“if I can’t read it on my phone in five minutes, it’s wrong”).
[OPERATOR STORY — Lesson 9]Tonight’s assignment
Run the prompt. Edit the per-story paragraphs into your own voice. Trim the system sketch to the minimum that’s honest. Drop the result into the workbook below — this is the input for Lesson 04.
Assignment · Section 09
Draft the high-level spec
Sign in to save your answers.Per-story paragraphs. Plus the three-list system sketch.
Done with this section? Review all your answers in one place.
Review my workbook →