The Specification Gap: Why AI Makes Bad Requirements Worse (Then Better)
David Liu
There's a gap in almost every product team, and most people don't even have a name for it. I call it the specification gap: the invisible distance between what a PM writes in a requirements doc and what engineers actually understand when they read it.
It's not a communication problem. It's a translation problem. And AI just made it much, much worse — and then immediately better.
The Specification Gap Has Always Existed
In the pre-AI era, the spec-to-code journey looked roughly like this:
- PM writes a PRD in Notion or Confluence
- Designer interprets the PRD into wireframes
- Engineer interprets the wireframes into code
- Everyone discovers the misinterpretations in QA
At each step, context is compressed and lost. The PM had a mental model. The designer had a different mental model. The engineer had a third. The product that shipped was the overlap — which is smaller than anyone intended.
Studies consistently show that software projects overrun estimates by 50-200%, and a disproportionate share of that isn't technical complexity. It's rework from misunderstood requirements.
The industry adapted. Agile tried to fix it with ceremonies. Continuous discovery tried to fix it with ongoing user interviews. Shape Up tried to fix it with “shaped” work. None of them fully solved the gap. They just gave it more structure.
What AI Did to the Problem
Then AI code generation arrived. Tools like GitHub Copilot, Cursor, and Claude dramatically accelerated the writing-code phase. An engineer who used to implement a feature in two days can now do it in half a day. This is genuinely great.
But here's the problem nobody talks about: when you speed up execution, the specification gap doesn't shrink — it compounds.
If an engineer used to spend 8 hours implementing something slightly wrong, now they spend 2 hours implementing something slightly wrong. The discovery that it's wrong hasn't accelerated at the same rate. Review cycles still take time. Demos still happen at the end of a sprint.
We're now generating wrong things faster.
There's a subtler issue too. AI-generated code looks more complete and polished than hand-written code. When a junior engineer writes buggy code, the scrappiness is often visible. When Claude writes code that misunderstands the requirement, it looks production-ready. The confidence gap is real, and it's getting people into trouble.
The Actual Root Cause
Here's what I've come to believe after watching dozens of product teams hit this wall:
The specification gap isn't a writing problem. It's a representation problem.
Natural language is inherently ambiguous. When I write “the user should be able to filter by date,” I mean something specific. But that sentence contains at least eight implementation decisions: What type of date? What interaction model? What happens on mobile? What's the default state? Does it persist across sessions? What happens to in-progress searches?
A skilled engineer with five years of context about your product will infer most of those answers correctly. A junior engineer won't. An AI model, drawing on general patterns rather than your specific product context, will make plausible but often wrong assumptions.
The problem gets worse as teams grow and context diffuses. The PM who wrote the spec might have institutional knowledge about why certain decisions were made. That knowledge rarely makes it into Jira.
Why Traditional Solutions Fail
The standard advice is “write better requirements.” This is technically correct and practically useless.
PMs already know they should be more specific. The problem is that the cost of writing truly exhaustive requirements is enormous — often more expensive than just letting engineers ask questions during implementation. So teams converge on a level of specificity that's good enough for senior engineers who have context, and insufficient for everyone else.
Design tools tried to bridge this gap by making the design artifact the source of truth. If Figma shows exactly what the interface should look like, maybe engineers can read the design instead of the spec. This helps with visual decisions but completely ignores behavior, edge cases, state management, and data modeling.
Tickets in Jira tried to make requirements smaller and more digestible. But a ticket is just a compressed PRD. The information loss is still there; it's just smaller in scope.
A Different Approach: Structured Specification
The more promising direction isn't about writing more. It's about writing differently — in a format that machines can reason about and humans can read.
Think about what a compiler does. You write code in a high-level language, and the compiler translates it into something a machine can execute precisely. It doesn't guess. It doesn't interpret. It operates on explicit, unambiguous instructions.
Product requirements have historically been the opposite: high-ambiguity natural language passed down a telephone game until something ships.
What changes when you represent requirements in a structured, machine-readable format that preserves intent?
- AI can generate code from spec, not from interpretation of spec. When the requirement explicitly models state, events, and behavior — not just UI — the code that comes out the other side is closer to what was intended.
- Gaps become visible before implementation. A structured spec that asks “what happens in the empty state?” forces that question before an engineer asks it at 4pm on a Friday.
- Context travels with the requirement. The “why” behind a decision doesn't need to live in a Slack thread from six months ago.
This is directionally how ProductOS approaches it. Instead of treating the PRD as a document that gets handed off, it treats the PRD as a living artifact that connects directly to design and code generation. The specification isn't compressed into a ticket — it's the source of truth all the way to deployment.
What This Means for Product Teams Right Now
You don't need to overhaul your entire workflow to start closing the specification gap. A few concrete changes make a meaningful difference:
1. Model behavior, not just UI
Most requirements describe what something looks like. The hard work is describing what something does: what triggers state changes, what the valid states are, what errors look like, what happens when the network is slow. Force yourself to write this explicitly, even when it feels obvious.
2. Write requirements as assertions, not descriptions
Instead of “the search bar should search for products,” write “given a search query, the system returns matching products within 500ms, ordered by relevance score, with a minimum of one result or an empty state message.” The second version leaves almost nothing open to interpretation.
3. Create a lightweight decision log
Not everything belongs in the ticket. But decisions that are non-obvious — especially ones that contradict common patterns — should be captured somewhere the team can find them. The question “why is this feature scoped this way?” should have an answer that isn't “ask the PM.”
4. Use AI to expose ambiguity, not just generate
Before handing requirements to engineers, run them through a language model with the prompt: “What questions would a developer have about this spec? What ambiguities would lead to wrong implementation?” This surfaces holes you can fill before they become bugs.
5. Review specs, not just code
Teams invest heavily in code review. Almost nobody reviews specifications with the same rigor. A spec review where engineers read requirements before writing any code, and raise questions, is one of the highest-leverage activities a team can do. It takes an hour. It saves days.
The Bigger Picture
The specification gap is a symptom of something deeper: product development tools were built for a world where humans do the executing. The PM writes for human engineers. The designer makes decisions that human engineers will implement.
As AI takes on more of the execution work, the interface between human intent and machine execution becomes more important, not less. The quality of a specification now determines the quality of an entire build pipeline, not just a single sprint.
Teams that understand this early will adapt. They'll invest in specification quality, not just velocity. They'll treat requirements as first-class artifacts, not administrative overhead. They'll build systems where context travels intact from idea to code — instead of being ground down at every handoff.
The companies that win the next five years won't be the ones with the most AI tools. They'll be the ones who figured out how to write clear requirements for the AI agents doing their work.
The gap is real. Closing it is a choice.
ProductOS is built for teams who want to close the specification gap — connecting requirements, design, and code generation in a single workspace. Start building at productos.dev. Learn more about our approach at productos.dev.