The Spec Is a Lie: Why Modern Product Teams Are Moving to Living Systems
James Mitchell
Three months ago, I watched a product manager spend two full days writing a requirements document. Forty-seven pages. Confluence tables, user story matrices, edge case appendices. It was genuinely impressive work.
The engineering team read it once, bookmarked it, and then — like every team before them — built something slightly different. Not because they were careless. Because by the time the first sprint ended, the spec was already wrong.
This is the story of almost every product team I’ve talked to in the last year. And it’s pushing the best of them to abandon the spec entirely — not for chaos, but for something more honest about how software actually gets built.
The Problem With “The Spec”
Product specifications exist because someone, at some point, needed to answer the question: “What are we building?” That’s a legitimate question. The spec was the answer.
But the spec carries an assumption that’s quietly killing teams: that you can fully understand what you’re building before you build it.
You can’t. Not really. You can approximate. You can sketch. You can write down your best current understanding. But the moment you declare something a “requirement” and lock it in a document, you’ve made a bet that reality will cooperate — that users will behave as modeled, that technical constraints are known, that the market won’t shift by Tuesday.
The spec is a snapshot masquerading as a plan.
And here’s where it gets worse: teams treat specs as contracts. Engineers build to the spec. QA tests against the spec. PMs defend the spec in stakeholder calls. The document accumulates authority it never deserved, and changing it feels like admitting failure rather than learning something true.
What “Living Systems” Actually Means
When I say teams are replacing specs with living systems, I don’t mean “we write our specs in Notion now and update them sometimes.” I mean something more structural — a fundamental shift in where product knowledge lives and how it evolves.
The teams doing this well share a few characteristics:
1. The source of truth is in the code, not above it
In a living system, the canonical description of what the product does is the product. Not a document about the product. This sounds obvious until you realize how much of traditional product work is devoted to maintaining a parallel textual reality — the spec, the PRD, the design doc — that describes the product in prose form, separate from the product itself.
One engineering lead I spoke with put it bluntly: “Our wiki was a graveyard. Documentation that was accurate when written, wrong six months later, and nobody’s job to fix.” Their solution wasn’t better documentation culture. It was inverting the relationship — using tools that derive documentation from behavior, not the other way around.
2. Decisions are made at the last responsible moment
Traditional specs front-load decisions. Everything gets resolved in the planning phase, on paper, before code exists. This feels thorough. It’s actually a form of waste — spending decision-making energy on questions you can only truly answer once you’re in them.
The shift is toward what lean practitioners call “last responsible moment” decisions: you decide as late as you can without creating downstream cost. Ship the rough cut, watch how users actually use it, then decide. The spec was forcing decisions before they were ripe.
3. Context travels with the artifact
This might be the most underrated piece. In the old model, context lives in documents, slack threads, and people’s heads — all separate from the thing being built. In a living system, the why travels with the what. Code comments, PR descriptions, feature flags with descriptions, decisions logged in ADRs linked from the code — the artifact knows its own history.
This isn’t just organizational hygiene. It changes how teams make decisions. When a developer is looking at a piece of code and the context is right there — “we did this because X, we considered Y, the tradeoff was Z” — they can update it intelligently. Without that context, they guess, or they’re afraid to touch it at all.
The Formats That Are Replacing the Spec
So what does this look like in practice? A few patterns keep coming up:
Working Agreements Over Requirement Documents
Instead of a 40-page PRD, some teams are adopting a much shorter “working agreement” — a one-pager that answers: What problem are we solving? Who’s the user? What does success look like? What are we explicitly not doing? And critically: when do we revisit this?
The last question is the important one. It forces honesty about the document’s shelf life. You’re not pretending this is permanent truth. You’re saying: this is our best current bet, valid until [date] or until [condition].
Decision Logs (Lightweight ADRs)
Architecture Decision Records started in engineering but are spreading into product. The format is simple: Date, Context, Decision, Consequences. They live close to the code, they’re written to be revised, and they treat decisions as time-stamped positions rather than eternal truths.
The product version might look like: “On March 15th, we decided not to build batch export because our top-tier users do it infrequently enough that the manual workaround is acceptable. Revisit if support tickets about this hit 5/week.” That’s more useful than any spec section because it tells you when the decision was made, why, and when it should be reconsidered.
Feature Flags as Product Infrastructure
There’s a reason feature flag systems keep appearing in these conversations. Flags do something subtle and important: they make product decisions reversible. The spec assumes finality — a feature is in or it’s out. Flags acknowledge uncertainty — a feature is on for some users, monitored, and adjustable without a deploy.
When you can change what the product does without a release cycle, the urgency to get the spec “right” upfront decreases. You’re not committing to a permanent reality. You’re running an experiment with a hypothesis you can update.
Embedded Metrics, Not Success Metrics in Docs
Classic specs often include a “success metrics” section: “This feature will be successful if X% of users do Y.” Then the feature ships, six months pass, and nobody remembers to check those metrics — or the tooling to check them was never built.
The living system version embeds metrics directly into the feature’s existence. The feature flag dashboard shows adoption. The analytics event fires automatically. The dashboard that matters is built alongside the feature, not promised in a doc. Success is something you watch, not something you define once and forget.
The Org Change Nobody Talks About
Here’s the uncomfortable part: most teams that try to kill the spec fail. Not because the ideas are wrong, but because the spec was doing organizational work they didn’t account for.
The spec is a communication artifact. It’s how PMs talk to engineers, how engineers talk to design, how teams talk to leadership. Rip it out without replacing the communication function, and you get chaos — people building different things, stakeholders surprised by launches, no shared language for what’s in scope.
The teams that successfully transition to living systems are deliberate about replacing that function:
- More frequent syncs, shorter prep: Instead of a long async spec review, they have short regular alignment conversations. Less document, more dialogue.
- Demos replace status reports: The running software is the status update. “Here’s what it does today” is more honest than “here’s what the spec says it will do.”
- Stakeholder education: Leaders who are used to reviewing specs need to learn to review prototypes, metrics, and decision logs. This takes explicit effort.
The spec, at its best, was a forcing function for alignment. Living systems need new forcing functions. Building them is the real work.
Not Every Team Should Do This
Let me be direct: the living system approach is not universally right.
If you’re building medical devices, aerospace software, or anything where regulatory compliance requires documented specifications, this model has hard limits. If you’re a contractor building to a client’s requirements, the spec is the contract — you can’t unilaterally decide to replace it with “working agreements.”
Even in normal product companies, there are moments when a detailed spec is the right call: integrations with external partners who need precise API contracts, accessibility requirements that need to be systematically verified, security features where the threat model needs to be documented and reviewed.
The goal isn’t to eliminate documentation. It’s to stop treating the spec as the primary representation of your product’s future state — and to stop the organizational dysfunction that comes from pretending documents are more durable than they are.
A More Honest Relationship With Uncertainty
What I’ve come to think is that the best product teams are the ones with the most honest relationship with uncertainty. The spec was, in part, a way of managing anxiety about not knowing — if we write it all down, surely we’ve handled it.
But uncertainty doesn’t disappear because you wrote it down. It just hides. It shows up later, in sprint reviews, in support queues, in the quiet realization that the thing you specified isn’t the thing users needed.
Living systems don’t eliminate uncertainty either. They just keep it visible, which turns out to be much better than burying it. When the feature flag is on for 5% of users and you’re watching the metrics, you know what you don’t know. That’s the beginning of actually learning something.
The spec says: we figured it out.
The living system says: we’re figuring it out.
The second one is harder. It’s also true.
Priya Sharma is a product strategist who has worked with early-stage startups and scale-ups across Europe and Southeast Asia. She writes about the intersection of product process, engineering culture, and organizational change.