'Add a search bar' isn't a requirement — it's a hint. Most real engineering mistakes trace back further than the code, to a requirement nobody actually pinned down before work started.
2 min read
A request like "users should be able to search their orders" sounds concrete until you start asking the questions it doesn't answer: search by what field — order number, product name, date? Exact match or partial? Case-sensitive? What happens with zero results? Is this urgent or a nice-to-have for next quarter? None of those are implementation details — they're the actual requirements, and building before they're answered means building the wrong thing, confidently.
The practical fix is small but disciplined: rewrite every vague ask as a statement specific enough that you could write a test for it.
Vague: "Users should be able to search their orders."
Specific: "Given a logged-in user with orders, typing a partial product name
into the search box returns all of that user's orders whose
product name contains the typed text (case-insensitive), updated
as they type, with a 'No orders found' message when nothing matches."
The second version isn't more polished prose — it's a different, better artifact. It's specific enough to build against, specific enough to test against, and specific enough that a reviewer can actually tell if the delivered feature matches what was asked for.
The cost of an unclear requirement doesn't disappear when you skip clarifying it — it just moves later, to a code review, a bug report, or a frustrated "that's not what I meant" after the feature ships. Ten minutes of clarifying questions before writing code is reliably cheaper than the same misunderstanding discovered after the work is already done — and the habit of restating an ask back in specific, testable language is one of the highest- leverage things a software engineer can do that has nothing to do with writing code at all.
Check your understanding
A quick comprehension check — not tracked, not graded, just for you.
1. Why is 'add a search bar' considered a hint rather than a requirement?
2. What makes a rewritten requirement 'specific enough,' according to the practical test in this lesson?
3. Why are 'what's explicitly out of scope' questions worth asking before writing code?
Software Engineering Fundamentals