The Hollow Requirement

A requirement can be specific, structured, approved by five people, and still leave the most important decision unmade.

The document was approved. I approved it. So did the product lead, the tech lead, and the two stakeholders whose sign-off the process required.

Eighty-seven days later, three days out from the deadline, we found out that none of us had been approving the same thing.

Nothing was missing from that document. Every section was filled in, every requirement had a sentence, and the sentence that caused the damage was one of the clearest ones in the file.

It asked for a summarized periodic view of user activity: weekly, monthly, quarterly, yearly. One of the three core functions of the application. What got built was every one of those intervals, working correctly, displaying daily progress rows inside them. A single task appeared three times: 30% on Monday, 20% on Tuesday, 50% on Wednesday. Filter to the month and you got that repeated across a whole team, hundreds of rows deep, with the actual answer — which tasks got finished — nowhere on the screen. Four days of work to fix, and it slipped the deadline by a week.

What sign-off actually measures

I spent the first postmortem on the wrong question. I wanted to know how a requirement that specific had produced a build that wrong, and the honest answer turned out to have nothing to do with the requirement.

Approval measures the absence of objection. When I signed that document, what I was really saying was “I read this and nothing in it alarms me.” Same for everyone else in the chain. Five people confirmed they had no disagreement with a phrase, and because each of us silently supplied a working version of “summarized view” from our own experience, none of us had any disagreement to report.

The failure mode is that the ritual cannot detect the problem it is supposed to prevent. A missing requirement leaves a hole, and holes get noticed in review. A hollow requirement leaves a word. The document looked complete because every sentence was there. What was missing lived behind one of those sentences, in a place the review process never looked.

Experienced reviewers can be especially vulnerable to this class of problem because they are good at filling in gaps automatically. Expertise can make an ambiguous mechanism feel obvious without making the shared interpretation explicit.

The change I made

Approval no longer counts until someone reads it back. Before a requirement is closed, the person who is going to build it describes what they intend to build, in their own words, out loud or in writing. Not “yes, understood.” Not a thumbs-up in the thread. An actual description of the mechanism: what happens to the data, what the screen shows, and what gets decided along the way.

Then I listen for the divergence. Not for errors, and not for gaps they have spotted. For the moment their description and my expectation stop matching.

If I had done this on the requirement in question, the developer would have described building a filter that returns the records inside a date range. I would have heard it in one sentence, because that was not what I had in my head, and the whole thing would have cost minutes in week two instead of a week at day eighty-seven.

It works because it inverts who does the work. Standard review asks the reader to find what is wrong with the document. A read-back asks the builder to state what they are going to do. The mismatch surfaces as a side effect rather than as the goal.

The version I run before I get anyone else involved

The read-back needs a builder, and a builder is not always available at the moment you are writing. So I run a machine version first, on my own draft, before anyone has read it.

The instruction is not “review this requirement.” Asking a model to review something tends to produce a list of generic gaps. The instruction is to build from it and then confess what it had to decide on its own.

You are the developer who has been handed this requirement and starts building it tomorrow. Do not review it. Do not list what's missing. Do not ask me any questions.

Write two things.

1. THE BUILD. Describe what you are going to build, in your own words, as if you were explaining it to another developer at your desk. What happens to the data, what appears on the screen, what the user sees when they use it.

2. WHAT YOU DECIDED. Every point where the requirement did not tell you what to do and you picked something in order to keep going. For each one, state the choice you made and the alternative you rejected. Be exhaustive, including the choices that felt obvious. The decision you made without noticing you were making it is the one I need most.

Requirement: [PASTE]

Watch-for: Section 2 is the part that matters, and it is the part a model tends to make short. It fills gaps with reasonable defaults and can present them as though the requirement specified them. If the list is suspiciously short, ask for the implicit decisions again. This shows where a requirement can be read a second way; it does not tell you how your team will actually read it, so use it before the human read-back, never instead of it.

Running it without turning it into a process

Ask the builder, not the room. A read-back from someone who is not going to implement the thing tests little. The value is that this person’s understanding is the one that becomes code.

Own words, not the document’s words. If they read the requirement back verbatim, you have learned nothing. The mismatch only surfaces in paraphrase.

Run it on what you are confident about. Requirements people are already worried about get discussed at length. The one that hurt us was the one nobody had a question about. Confidence is a signal to check, not a reason to skip it.

I do not run this on every line. On a large document it is the core functions and anything where the output is described as a result rather than a screen: summarized, consolidated, aggregated, rolled up. Those are phrases that can hide logic.

Why this one was hard to catch

The document that caused this was, by any normal standard, a good document. It was specific, structured, and named the thing it wanted. If you had shown it to me cold, I would have approved it again.

That is why I stopped trying to write requirements that cannot be misread and started building a cheap way to find out whether they had been. The first goal is unrealistic. The second can happen while the mismatch is still cheap to fix.

This piece was first published on Substack. Read the original on Substack →