Topic 7 — Writing specs and user stories

Goal: Turn a prioritized idea into something a team can actually build.

Lesson 7.1 — What a spec is for

Maya has decided what to build next at Lumi: the budgeting app needs a way for people to export their spending data. She knows it matters. She just told the team in standup. And by lunchtime she has three Slack threads asking the same questions in different words. Export to where? For which users? Does it include last year's data? Sam wants to know before he writes a line of code.

She was clear in her own head. She just never wrote it down anywhere the team could act on without reading her mind.

That document is the spec (short for specification), sometimes called a PRD (Product Requirements Document). It exists to answer four questions before the back-and-forth starts:

• Why are we building this? The problem and the goal.
• Who is it for? The user.
• What should it do? The requirements, the picture of what "done" looks like.
• How will we know it worked? The success metric.

A spec is, at heart, a communication and alignment tool. The temptation is to measure it by page count, as if thirty pages means thirty pages of rigor. The only test that counts is whether the team reads it and builds the right thing without circling back ten times. A clear one-pager that aligns everyone beats a thirty-page document nobody finishes.

The spec that gets read and acted on beats the thorough one that sits in a tab.

Lesson 7.2 — Describe the "what," not the "how"

Maya's first draft of the export spec is four pages long, and it tells Sam which database table to read from and which CSV library to import.

Sam reads it and goes quiet, which from Sam is not a good sign.

A spec describes the what and why. It does not describe the how-to-build-it. Maya's job is to define the problem and the outcome she wants. The technical implementation belongs to the engineers, and the detailed design belongs to Priya.

Over-specifying is one of the most common things new PMs get wrong, and it costs them twice. First, it wastes the expertise of people who do this for a living. Sam has shipped exports before; he probably knows a faster library than the one Maya googled. Second, it quietly demoralizes a team that starts to feel like order-takers instead of problem-solvers.

There's a line to hold. Be crisp about requirements and constraints, the things that must be true. Stay open about implementation, the way they get there. "Users must be able to reset their password by email" is a requirement. "Use this specific library and this database table" is implementation, and Maya should leave it alone.

Telling experts what to achieve and trusting them with how is the mark of a PM people want to work with. It also tends to produce a better result.

Lesson 7.3 — User stories

"Let users export their data" is true, but Sam can't build "a sentence." It's a feature-sized lump, and a team can't pick it up, build it, or test it in one piece.

So Maya breaks it down into user stories: small slices written from the point of view of a person, using one simple template.

As a [type of user], I want to [do something], so that [benefit].

Here's the password-reset example in that shape: "As a new user, I want to reset my password by email, so that I can get back into my account if I forget it."

Three things happen when you write this way. The focus stays on the user and their goal instead of drifting into a technical to-do. The piece stays small enough to build and test in a short cycle. And that "so that" clause names the value, which lets everyone judge whether it's even worth doing.

A feature is usually a stack of these stories. Writing them this way keeps the whole team pointed at a person and a benefit, almost without anyone noticing it's happening.

Lesson 7.4 — Acceptance criteria

A week later, Sam says the password reset is done. Maya tries it, and the expired link from yesterday still works. Sam says that wasn't in the story. He's right. It wasn't.

This is the standoff every team has lived through. "It's done." "No it isn't." Both people are sincere, and both are working from a different picture of done.

The fix is acceptance criteria: a short, checkable list of conditions the story has to meet, agreed before anyone builds. For the password-reset story, that list might be:

• The user can request a reset link by entering their email.
• The link expires after 24 hours.
• A valid link lets the user set a new password.
• An invalid or expired link shows a clear error message.

Now "done" is something you can test instead of something you argue about. This is exactly what the QA tester checks against, and it's what lets everyone agree, objectively, that the work is complete.

There's a quiet diagnostic buried in here. If you sit down to write acceptance criteria and you can't, that's a signal you don't understand the story well enough to build it yet.

Lesson 7.5 — Slicing work well

Maya could hand Sam the whole export feature and disappear for a month. Or she could cut it into pieces that each do something real.

The cut matters more than people expect. Good slices are small, independently valuable, and testable — each one a usable piece, not half a wire dangling off nothing.

The technique to reach for is slicing vertically: a thin piece that runs end to end and actually works. The opposite, slicing horizontally, means "build all the backend," then "build all the UI," and you get nothing a user can touch until the very last day.

Think about a checkout feature. A good first slice is "a user can buy one item with a saved card." It's narrow, but it works front to back, and you can ship it and watch real people use it. Later slices add "multiple items," "a new card," "a discount code." Each one delivers value and teaches you something, which is the same incremental-release idea from Topic 3. You hand value over step by step and get feedback early, instead of vanishing for months and hoping.

Worked example — From a one-line idea to buildable work

Back to Maya and the roadmap line: "Let users export their data." Too vague to build, which is where we came in. Now she has the tools to fix it.

She writes a short spec, not an essay. Why: people have asked to back up their spending and analyze it elsewhere. Who: power users, the ones living in the app every day. Success metric: X% of power users run an export within a month of launch.

Then she slices it into stories, starting with the thinnest one that still earns its keep: "As a user, I want to export my records as a CSV, so that I can open them in a spreadsheet." Later slices follow: "...export as PDF..." and "...schedule a weekly export..." The CSV slice ships first and ships alone.

For that CSV story she writes acceptance criteria a tester can run down:

• There's an Export button on the records page.
• It produces a downloadable CSV with all the columns currently shown.
• It handles the case where there are zero records.
• It shows a clear error if the export fails.

And she does not tell Sam which library to use. That's his call.

What the team has now is something clear, testable, and shippable in slices, with nobody micromanaging the how. Sam knows exactly what "done" means for the first slice and is free to build it well.