The Most Expensive Requirement I Ever Wrote Was One Sentence Long
Twelve words. Three months of rework. One very angry customer support team.
Here’s the requirement:
The system should send customers a reminder before their payment is due.
Read it again. It looks fine, right? Clear, short, testable. I remember feeling quietly proud of it. No jargon, no fluff. Exactly what the stakeholder asked for. It went through review. Developers built it. QA tested it. It passed. And then it went live.
What happened next
The first complaint came in on day two.
A customer had paid her bill early, three days before the due date. The next morning she got a reminder telling her the payment was due. She called support, worried her payment hadn’t gone through.
By the end of the week, there were dozens of calls like that.
Then we found the second problem. Customers on auto-debit were getting reminders too. Some of them panicked and paid manually, so the bank debited them twice. Now support was handling refunds as well as confused calls.
Then the third. Reminders were going out at 2 AM, because that’s when the batch job ran. A few customers were not thrilled about a payment SMS in the middle of the night.
None of this was a bug. The system did exactly what the requirement said. It sent customers a reminder before their payment was due.
Fixing it took three months: new rules, extra testing, a pause on all reminders while we sorted it out, and a lot of apologetic emails. All because of one sentence I thought was finished.
The questions hiding inside one sentence
Later I sat down and pulled that requirement apart word by word. It was a bit humbling.
“Customers.” All of them? What about ones who’ve already paid? Auto-debit customers? Closed accounts? Customers in a payment dispute?
“A reminder.” By SMS, email, app notification? One reminder or several? What does it actually say?
Get SOUNDARYA SAINATHAN’s stories in your inbox
Join Medium for free to get updates from this writer.
“Before.” One day before? Seven? And at what time of day?
“Their payment is due.” Which date counts, the bill date or the grace period end? What if the due date falls on a holiday?
That’s more than ten unanswered questions in a sentence I’d called “clear.”
The stakeholder knew most of the answers. Of course paid customers shouldn’t get reminders. Of course not at 2 AM. They were so obvious to her that she never said them. And I never asked, because the sentence felt complete.
That’s the trap. Short requirements look clear because they don’t show you what’s missing. The dangerous ones aren’t the long confusing ones. They’re the short ones that everyone nods at.
How I stress-test requirements now
I still write short requirements. I just don’t trust them anymore.
Before anything goes to development, I do a quick “word by word” check. I circle every noun and every time word, and ask: which ones? how many? when exactly? what if not?
AI has made this much faster. I paste the requirement in with this prompt:
Here is a requirement: "[paste requirement]".
Go through it word by word. For each important word or phrase, list the questions a developer, a tester, and an unhappy customer might ask.
Then list the 3 scenarios most likely to cause problems in production if these questions are not answered.When I tried it on the reminder requirement afterwards, it caught the already-paid customers and the auto-debit problem in its first answer. It took about 20 seconds. I’ll let you imagine how I felt about that.
Then I take those questions back to the stakeholder. Not as a long document, just a quick list: “Before we build this, can you answer these six?” Most answers take them a minute. Each one could save weeks.
One more habit: I add a line to every requirement that says who should not be affected. “Customers who have already paid, or are on auto-debit, should not receive a reminder.” Writing down the exclusions catches more problems than anything else I do.
The lesson I keep relearning
A requirement isn’t finished when it’s clear to you. It’s finished when nobody can read it two different ways.
That reminder sentence is still pinned on my desk. Not because I’m proud of it. Because every time I write something that feels clean and simple, I look at it and ask myself, “Okay, but what am I not saying?”
Twelve words cost us three months. These days I spend twenty seconds asking AI to pick my sentences apart, and ten minutes asking the stakeholder the questions it finds. Best trade I’ve ever made.
What’s the shortest requirement that caused you the biggest headache? Share it in the comments. I have a feeling we’ve all got one.
