Requirements as the Contract
Week 3 · You meet your client in about 24 hours
Week 3 · You meet your client in about 24 hours
A manager asks for a system to track chemical containers. Chemists stop buying what is already down the hall. The safety office files its reports without a week of work.
Five months, before the compliance audit. Can you do it?
What he said
Save money on chemicals.
Cut the safety office's reporting work.
Be ready in five months.
What nobody knows yet
Who may request a hazardous chemical?
What happens to a half-empty container?
Is "the stockroom" one place or six?
What has to be in the report?
Business objectives are not requirements. Both are necessary. The gap between them is your job.
Project Pulse started as a complaint about spreadsheets.
docs/requirements/ today:
project-glossary.mdvision-and-scope.md (about 11,000 words)use-cases.mdbusiness-rules.mdsoftware-requirements-specification.mdOPEN-ISSUES.mdGlossary
One word, one concept.
Started in the first meeting, because your client hands you the vocabulary whether you ask or not.
Vision and scope
Why this exists, what success looks like, who cares, and what is not in it.
You will not finish it Friday. You will start it.
| Lead | Asks. One person, not four. |
| Scribe | Writes. Does not ask. Captures exact words, especially nouns. |
| Observer | Watches for what is not said. |
Say what you understood, in your own words. Watch for the correction.
A client who is nodding may just be polite. A client correcting you is engaged.
Sony ran a focus group on a yellow sport Walkman. The room loved it.
On the way out, free Walkman, two tables. Black on one, yellow on the other.
What people say in an interview is data about the interview.
| Instead of | Ask |
|---|---|
| Would you use a dashboard? | Walk me through the last time you needed that number. What did you do? |
| Is this important? | If we ship only one thing in December, which one? |
| Would this save time? | How long does it take today, and how do you know? |
| Do you like this? | Show me the spreadsheet you use now. |
"I need a drop-down of states."
That is not a requirement. That is a solution, already chosen, wearing a requirement's clothes.
The client asked for a faster horse, so we shipped a horse with a spoiler. It tested green.
Business rules exist whether or not your software does. Write them down the second you hear one.
BO-grading-time: reduce the instructor's time to grade peer evaluations by 50%.
"Make grading better." Is that a business objective?
"How will you know this worked?"
Good question. Not the hard one.
"What is that number today?"
Your client says "cycle" in one sentence and "sprint" in the next.
Ask which they mean, in the room, while they are in front of you.
There are two hard problems in computer science: cache invalidation, naming things, and off-by-one errors.
Two words for one concept, and nothing in the repository says so.
You get a Team class and a Group table. A submitReport endpoint and a war_entry row. The agent reads what is already there and imitates it, faithfully reproducing the inconsistency, and invents a plausible synonym for anything the repository never names.
How Project Pulse used to do it
BO-1, BO-2, BO-3
RI-1 … RI-4
How it does it now
BO-grading-time
RI-cloud-cost
We renumbered the requirements. Good news: BO-1 through BO-7 are all still there. Bad news: they are not the same seven.
A marketing manager wants one small button added. "The developers are going to be in the code anyway. How hard is one tiny feature?"
Write down what is out as explicitly as what is in.
Twelve minutes. Laptops open, one per team.
Then do the part it cannot do.
Which ten do you take, and why?
A requirements analyst walks into a bar and orders a beer, 0 beers, 999999999 beers, a lizard, and −1 beers. The bar ships flawlessly. The first real customer walks in and asks where the bathroom is.
docs/requirements/ in your team repo.OPEN-ISSUES.md.No requirements document has ever survived contact with a client unchanged. That is not failure, that is the process working.
Studio: Napkin round 0 on your own project, sealed. Then draft the glossary and vision and scope, on branches, one section each.
Repository owner: turn on branch protection before Friday.