Case Study 1 — "The System Should Be Fast": One Sentence, Six Weeks, and the Rewrite That Would Have Saved Them

A worked transformation. We take the chapter's flagship vague requirement and follow it all the way from the disagreement it caused to the testable statement that resolves it—and the test, traceability, and verification it unlocks. Fictional but realistic; the failure is one of the most common in the industry.

The failure

A team at a mid-size software company—call it the search team—was asked to improve product search. The requirements document, signed off by both the product owner and the engineering lead, contained this line:

REQ-12. The system should be fast and responsive when users search.

Everyone read it and nodded. The engineers built a new search backend, optimized it, ran their own checks (queries came back in well under two seconds), demoed it, and shipped. The product owner used it, frowned, and filed a complaint: search feels sluggish. The engineers were baffled—it was three times faster than the old system. After a tense meeting, the disagreement surfaced: the product owner had meant "fast" to mean near-instant, like typing into a desktop search box—results appearing as you type. The engineers had meant "fast" to mean a single search returns in under two seconds, which is fine for a web app. Both had signed off on REQ-12. Both were certain they'd agreed. The eleven words had carried two different products, and nobody discovered it until six weeks of work had been built on the gap.

Notice what the defect was not. The code wasn't buggy. The engineers weren't careless—they hit the target they understood. The product owner wasn't unreasonable—"fast" genuinely meant something specific to them. The defect was in the sentence: "should be fast" was a wish, not a requirement, because there was no test that returned pass or fail, so two competent readers read opposite meanings into it and the document gave them no way to notice.

The diagnosis

Run REQ-12 through the chapter's three properties:

And the keyword: "should" signaled this was a recommendation, not even mandatory—so strictly, an engineer could have shipped something slow and still claimed conformance. Nobody intended that; the keyword was chosen carelessly, the way "should" gets used in ordinary speech.

The threshold question exposes the whole failure in one line: what test returns pass or fail on "the system should be fast," and would the product owner and the engineers run the same test and get the same answer? There is no such test—which is precisely why they got different answers in the product owner's head instead of in a test harness, six weeks too late.

The rewrite

The fix is not to write a longer sentence. It's to do the work the original sentence let everyone avoid: decide what "fast" actually means, as a number, under a condition, with a test. That conversation—the one the vague requirement postponed—is the entire value of writing the requirement well. Here it is, surfaced and resolved:

The product owner, asked "fast like what?", said: results should appear as the user types, within a quarter-second, so it feels live. The engineers, hearing an actual number, said: that's an autocomplete/typeahead feature, not page-load search—and 250 ms at that scale is achievable but it constrains the architecture. The disagreement that had cost six weeks took fifteen minutes to resolve once a number was on the table. The rewritten requirements:

• REQ-PERF-001. As the user types in the search box, the system SHALL return updated suggestions within 250 ms at the 95th percentile, measured at the API boundary, under a sustained load of 500 concurrent users.
• REQ-PERF-002. When the user submits a full search, the system SHALL return the results page within 800 ms at the 95th percentile under the same load.
• REQ-PERF-003. The system SHALL display a loading indicator within 100 ms of any search action that has not yet returned, so the interface never appears frozen.

What changed, and why each change matters:

• "Fast" became three numbers under stated conditions (250 ms typeahead, 800 ms full search, 100 ms loading indicator, all at p95 under defined load). There is now exactly one reading.
• The compound split into atomic requirements—typeahead latency, full-search latency, and perceived-responsiveness are three different things the original "fast and responsive" had blurred. The product owner's real concern ("feels live") turned out to be mostly REQ-PERF-001 and REQ-PERF-003, not raw search speed at all—a distinction the vague word had completely hidden.
• "Should" became "SHALL"—these are mandatory, and saying so commits the team.
• The numbers are measured at a defined point (the API boundary) under a defined load (500 concurrent users) at a defined percentile (95th). Without those conditions, even "250 ms" would be ambiguous (250 ms on whose machine, under what load?)—the same lesson as a replicable Methods section (Chapter 13): a measurement is meaningless without its conditions.

What the precision unlocks

A testable requirement doesn't just prevent the argument—it makes the rest of the engineering pipeline possible. Each rewritten requirement now flows downstream:

A test case can verify it. REQ-PERF-001 gets a test case that any tester can run to the same verdict:

TC-PERF-001 (verifies REQ-PERF-001) — Seed the index with the reference dataset; drive 500 concurrent users issuing the standard typeahead query stream for 10 minutes; record the suggestion-response distribution at the API boundary. Pass if p95 ≤ 250 ms for the full window (warm-up excluded).

It traces both ways. REQ-PERF-001 traces back to the product owner's actual need ("feels live as I type") and forward to TC-PERF-001 and to the design decision it constrains (a typeahead service with a prefix index, documented in the design doc). The traceability matrix has no blanks for this requirement: it's sourced and it's verified.

The design conversation gets sharper, too. Hearing "250 ms typeahead at 500 users," the engineers could say up front which architectures could hit it and which couldn't—a conversation worth having before six weeks of building, not after.

The lesson

The cost of the vague requirement wasn't the eleven words. It was six weeks of work built on a disagreement the words concealed. The rewrite didn't require more skill or more words—it required doing the thinking the vague sentence let everyone skip: what does "fast" mean, as a number, under what condition, verified how? That question is uncomfortable because it forces a decision, and the vague version felt like agreement precisely because it let everyone keep their own private definition. A requirement that feels like easy agreement is often a disagreement that hasn't surfaced yet. Writing it testably is how you surface it—on paper, in fifteen minutes, instead of in a demo, after six weeks.

Back to: Chapter 33 · Case Study 2 · Exercises · Key Takeaways