WEEK 3Wednesday

Requirements as the Contract

Week 3 · You meet your client in about 24 hours

Full detail: the spec driven requirements module →1 / 32
WEEK 3Wednesday

Two volunteers

Gerhard

Gerhard

Senior manager, Contoso Pharmaceuticals.

He is paying for this.

Cynthia

Cynthia

Manager of the Contoso IT department.

She has to build it.

Full detail: the spec driven requirements module →2 / 32
WEEK 3Wednesday

Gerhard opens

Gerhard

Gerhard

"We need to build a chemical tracking information system. The system should keep track of all the chemical containers we already have in the stockroom and in laboratories. That way, the chemists can get some chemicals from someone down the hall instead of always buying a new container. This should save us a lot of money.

Also, the Health and Safety Department needs to generate government reports on chemical usage and disposal with a lot less work than it takes them today.

Can you build this system in time for the compliance audit in five months?"

Full detail: the spec driven requirements module →3 / 32
WEEK 3Wednesday

Cynthia: not yet

Cynthia

Cynthia

"I see why this project is important, Gerhard.

But before I can commit to a schedule, we'll need to understand the requirements for the chemical tracking system."

Full detail: the spec driven requirements module →4 / 32
WEEK 3Wednesday

"I just told you my requirements"

Gerhard

Gerhard

Gerhard was confused.

"What do you mean? I just told you my requirements."

Key point

He is not being difficult. He genuinely believes he just did.

Full detail: the spec driven requirements module →5 / 32
WEEK 3Wednesday

Cynthia: those were objectives

Cynthia

Cynthia

"Actually, you described some general business objectives for the project. That doesn't give me enough information to know what software to build or how long it might take.

I'd like to have one of our business analysts work with some users to understand their needs for the system."

Full detail: the spec driven requirements module →6 / 32
WEEK 3Wednesday

Gerhard: the chemists are busy

Gerhard

Gerhard

Gerhard protested.

"The chemists are busy people. They don't have time to nail down every detail before you can start programming.

Can't your people figure out what to build?"

Full detail: the spec driven requirements module →7 / 32
WEEK 3Wednesday

Cynthia: we are not chemists

Cynthia

Cynthia

"If we just make our best guess at what the users need to do with the system, we can't do a good job. We're software developers, not chemists.

I've learned that if we don't take the time to understand the problem, nobody is happy with the results."

The agent

Your agent is not a chemist either, and it will never say so.

Full detail: the spec driven requirements module →8 / 32
WEEK 3Wednesday

Gerhard: just build it

Gerhard

Gerhard

Gerhard insisted.

"We don't have time for all that. I gave you my requirements.

Now just build the system, please. Keep me posted on your progress."

Full detail: the spec driven requirements module →9 / 32
WEEK 3Wednesday

What he actually gave her

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?

Key point

Business objectives are not requirements. Both are necessary. The gap between them is your job.

Full detail: the spec driven requirements module →10 / 32
WEEK 3Wednesday

Then what is a requirement?

Requirements are defined during the early stages of a system development as a specification of what should be implemented. They are descriptions of how the system should behave, or of a system property or attribute. They may be a constraint on the development process of the system.

  • Behave: what it does
  • Property or attribute: what it must be, and what its data looks like
  • Constraint: how you are allowed to build it
Key point

"The requirements" is an umbrella over several kinds of information, not one list of features.

Full detail: the spec driven requirements module →11 / 32
WEEK 3Wednesday

This is what one page becomes

Project Pulse started as a complaint about spreadsheets.

docs/requirements/ today:

  • project-glossary.md
  • vision-and-scope.md (7,500 words)
  • use-cases.md (43,700 words)
  • business-rules.md
  • software-requirements-specification.md
  • OPEN-ISSUES.md
Full detail: the spec driven requirements module →12 / 32
WEEK 3Wednesday

Two of those are yours by Friday

Glossary

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.

Full detail: the spec driven requirements module →13 / 32
WEEK 3Wednesday

Thursday: three roles, agreed before you walk in
Lead Asks. One person, not four.
Scribe Writes. Does not ask. Captures exact words, especially nouns.
Observer Watches for what is not said.
Full detail: the spec driven requirements module →14 / 32
WEEK 3Wednesday

Shape of the hour

  • 10 min. The business: why this, why now.
  • 30 min. The process as it works today, step by step.
  • 10 min. Scope: what is in, what is out.
  • 10 min. Read back what you heard.
Full detail: the spec driven requirements module →15 / 32
WEEK 3Wednesday

The ten minutes teams skip

Say what you understood, in your own words. Watch for the correction.

Key point

A client who is nodding may just be polite. A client correcting you is engaged.

Full detail: the spec driven requirements module →16 / 32
WEEK 3Wednesday

Everyone said yellow. Everyone took black.

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.

Key point

What people say in an interview is data about the interview.

Full detail: the spec driven requirements module →17 / 32
WEEK 3Wednesday

Ask the question that costs something

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 by the final demo, 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.
Full detail: the spec driven requirements module →18 / 32
WEEK 3Wednesday

Ask why until you reach the need

"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.

Full detail: the spec driven requirements module →19 / 32
WEEK 3Wednesday

Listen for the rule

  • "Only lab managers may..."
  • "Must comply with..."
  • "Unless it's been more than a year."

Business rules exist whether or not your software does. Write them down the second you hear one.

Full detail: the spec driven requirements module →20 / 32
WEEK 3Wednesday

Business objectives carry a number

BO-grading-time: reduce the instructor's time to grade peer evaluations by 50%.

Ask the room

"Make grading better." Is that a business objective?

Full detail: the spec driven requirements module →21 / 32
WEEK 3Wednesday

Objectives come in two flavors

Financial Nonfinancial
Save $X per year spent on a legacy system. Cut the data error rate to no more than X%.
Reduce monthly support cost from $X to $Y in Z months. Comply with specific federal and state regulations.
Reach revenue of $X within Y months. Reduce turnaround to X hours on Y% of requests.
Achieve X% return on investment within Y months. Raise satisfaction to at least X within Y months.
Key point

Your client's objectives are almost all in the right-hand column.

Full detail: the spec driven requirements module →22 / 32
WEEK 3Wednesday

The follow-up nobody asks

"How will you know this worked?"

Good question. Not the hard one.

Key point

"What is that number today?"

Full detail: the spec driven requirements module →23 / 32
WEEK 3Wednesday

One word, one concept

Your client says "cycle" in one sentence and "sprint" in the next.

Key point

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.

Full detail: the spec driven requirements module →24 / 32
WEEK 3Wednesday

What happens without one

Two words for one concept, and nothing in the repository says so.

The agent

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.

Full detail: the spec driven requirements module →25 / 32
WEEK 3Wednesday

`BO-3` or `BO-grading-time`?

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.

Full detail: the spec driven requirements module →26 / 32
WEEK 3Wednesday

The sentence you will need when the client asks for more

A marketing manager wants one small button added. "The developers are going to be in the code anyway. How hard is one tiny feature?"

Key point

Write down what is out as explicitly as what is in.

Full detail: the spec driven requirements module →27 / 32
WEEK 3Wednesday

Your turn: build Thursday's script

Twelve minutes. Laptops open, one per team.

  • Open the guide, select all, copy: raw.githubusercontent.com/tcu-cosc-40943/course-templates/main/requirements/client-interview-guide.md
  • Give your agent that, your one-page brief, and the role. "You are an experienced business analyst."
  • Ask for two things: your domain's version of every question in the guide, and a plain-language primer on this client's acronyms.
  • It will give you about thirty questions.
The agent

Then do the part it cannot do.

Full detail: the spec driven requirements module →28 / 32
WEEK 3Wednesday

Let it interview you

  • "Interview me about this brief. When I say ask the client, add it to the guide."
  • Answer what the brief already tells you.
  • Everything else: Other, then "ask the client".
Key point

You cannot answer for the client.

Full detail: the spec driven requirements module →29 / 32
WEEK 3Wednesday

Thirty questions. Forty-five minutes.

Key point

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.

Full detail: the spec driven requirements module →30 / 32
WEEK 3Wednesday

Before you walk in

  • Listen before you build. Brainstorm after the read-back, not in minute five.
  • Assign the three roles tonight.
  • Send your client the shortlist the day before. They arrive with answers instead of promises.
  • Copy the templates into docs/requirements/ in your team repo.
  • Scribe has client-interview-guide.md open in the meeting. Commit it the same day.
  • Everything you could not answer goes in OPEN-ISSUES.md.
Pitfall

No requirements document has ever survived contact with a client unchanged. That is not failure, that is the process working.

Full detail: the spec driven requirements module →31 / 32
WEEK 3Wednesday

Friday

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.

Full detail: the spec driven requirements module →32 / 32

Requirements as the Contract

→ space PgDn
Next step or slide
← PgUp
Back
↓ S
Skip to the next slide
O
Overview of all slides
N
Speaker notes
B
Black the screen
Ctrl+P
Print / PDF handout, one slide per page