Clarity Was Always the Bottleneck

I saw a hot take recently:

Agile is the new Waterfall.

The author argued that AI has made coding so fast that we’ve circled back to the same problem waterfall had: figuring out exactly what to build. The conclusion:

Maybe it’s time to obsess over requirements documents again. Maybe waterfall had something right about spending serious time upfront defining what we’re actually building.

They’re right about one thing. Clarity is the bottleneck. They’re wrong about almost everything else.

The Agile Manifesto says:

Working software over comprehensive documentation.

Not “working software instead of documentation.” That matters. The people who read it as a license to skip thinking before coding misread it; deliberately
or otherwise. Eliminating documentation was never the point. Having the right documentation at the right time, in the
right form, for the right people was the point. Teams that interpreted “agile means no docs” were not being agile. They
were being sloppy and calling it “modern.”

AI Didn’t Create the Problem

Here is what the post gets backwards: the bottleneck has never been coding speed.

The author writes that “the coding part is lightning fast” with AI and concludes we need to go back to upfront documentation to match that speed. But if clarity was always the constraint, and it was, then AI didn’t create a new problem. It revealed an existing one more harshly. The organizations that were masking poor product clarity with slow delivery cycles now have nowhere to hide. AI accelerates the path to production. What it cannot do is figure out whether you are building the right thing. That was always the hard part.

When we moved from quarterly releases to daily delivery, the first roadblock we hit wasn’t a technical problem. It was a clarity problem. We couldn’t do continuous integration without committing tested changes. We didn’t know what to test for with only vague requirements. It was a constant rework loop. Code something, ask the product manager if that was what they meant, rework it. On the surface, it looked like a coding issue. It was an information supply chain issue. We found Behavior-Driven Development (BDD) because we needed shared understanding of behavior before writing code, not because someone decided documentation was back in fashion. Moving faster exposed what slow delivery had been hiding. AI does the same thing, just faster and with less mercy.

Waterfall’s Problem Wasn’t Documentation

The author describes the old waterfall problem accurately:

We’d spend forever on documentation, then forever on development. By the time we shipped, users hated it because it wasn’t what they wanted.

The problem there was not that they documented. The problem was that they documented everything upfront before they could know what they needed, treated that documentation as truth, and built accordingly. The document became the focus. The user became an afterthought.

Maybe waterfall had something right about spending serious time upfront defining what we’re actually building.

This conflates two different things. Spending time to understand what you are building is good. Believing you can understand everything upfront before you start is the trap waterfall falls into. There is also a scale problem buried in the advice. “Spending serious time upfront defining what we’re actually building” means something very different for a project than it does for the next small change. For a project, you need a testable value hypothesis and enough architectural clarity to start delivering. For the next increment, you need a user story refined to testable acceptance criteria. Those are not the same activity and they do not require the same investment. Conflating them is how teams end up producing a Business Requirements Document, a Functional Specification, a System Requirements Specification, a Technical Design Document, a Use Case catalog, and a test plan for work that should have started with a user story and a handful of BDD acceptance scenarios.

The value hypothesis that starts a real delivery cycle is not a comprehensive requirements document. It is a testable statement: we believe delivering this capability will produce this outcome. You learn from delivering it. You update the hypothesis. You deliver again. The documentation that supports this process, user stories, acceptance criteria, BDD scenarios, is living. It changes as you learn.

Catching Up Means Learning From the Past

The post ends with:

Time to catch up.

The irony is that the advice to return to requirements-document obsession is not catching up. It is retreating to a model that failed before AI existed and will fail faster with it. AI does not change the information supply chain that runs from value hypothesis to validated outcome. It does not make upfront certainty more achievable. It makes the cost of building the wrong thing faster to accumulate.

The actual lesson here is the one agile was always teaching and too many teams ignored: get clarity early, get it collaboratively, get it in a form that can be tested and updated, and keep it close to the code. That is not waterfall. That is not “return to documentation.” That is the discipline of knowing what you are building before you build it, without pretending you know everything you will ever need to know on day one.

The bottleneck is clarity. It always was. The answer is not a requirements document. The answer is a practice that
continuously creates and validates shared understanding across the entire team. Call it BDD. Call it story refinement.
Call it spec driven development. Call it whatever you want. Just do not call it waterfall and do not call its absence agile.