I Don't Read My Own Specs, and That's the Whole Point
Field Notes from The Build – No. 2 || Strategy from the drafting table. Lessons from the keyboard.
Just like Jason Voorhees, the agile-versus-waterfall debate never dies – it keeps coming back. It comes back because it’s a useful argument, and because every new wave of developers eventually has to reach their own conclusions about how much planning is enough and how much is too much. The current resurgence has a particular flavor – it lives mostly on LinkedIn and YouTube, and it leans hard against specs. Specs are heavy. Specs are corporate. Nobody reads them. Just ship. Waterfall is dead. The dinosaurs of the old way are still scolding us from the boardroom while the rest of us iterate.
There is something true in that critique, and there is something the critique is missing. Both halves are worth taking seriously, because building a real product in 2026 means navigating both at once.
The part that’s true is straightforward. The dead corporate version of a spec – the thousand-page document nobody reads, the approval chains, the false certainty, the planning that calcifies into fiction – really is a waste. That’s not the same thing as saying specs are a waste. It’s saying that one particular implementation of a spec is a waste, and confusing the implementation with the concept is the kind of category error that lets people argue against object-oriented programming because they once saw a bad Java codebase. The bad version of anything is always bad. The interesting question is whether the good version still has work to do.
The bigger problem with the current debate is that it’s being conducted in 2026 with the same binary it had in 2014, which in AI years is roughly the Cretaceous. The debate certainly is not extinct, but the framing of it is. Both sides of the argument still assume that a spec is a document a human writes for another human to read. Even when the spec gets handed to an AI rather than a human, the assumption underneath stays the same – the spec is a static artifact passed across a boundary, used as a one-time briefing rather than as a living substrate the work persists within. From that premise, the entire shape of the debate makes sense. Specs are heavy because humans are slow readers. Specs feel like waste because the people they’re written for never finish them. Defending specs makes sense from inside that frame. So does dismissing them. The two sides are both correct, and they’re both arguing about the wrong thing.
Before getting to what I actually think the debate is missing, there’s a useful principle from the older argument worth keeping, because it dissolves the binary on its own. Some decisions in front of you are expensive to reverse. Some are cheap. Architecture is expensive. A button label is cheap. You don’t iterate your way into a data model; you iterate from one. The cost of being wrong on the foundation is high, and the cost of thinking carefully about it up front is low. That phase rewards real specs. The wiring phase, where you’re shaping what the user sees and how a flow feels and where the copy lands, is different. Those things only reveal themselves once people start using them, and heavy specs there would actively hurt the work. The principle is simple: match the process weight to the reversibility of the decision. Spec the expensive, iterate the cheap.
Most serious builders already work some version of that, whether they call it that or not. The agile-versus-waterfall debate falls apart the moment you accept that different decisions in the same project deserve different amounts of upfront thinking. But the principle still isn’t the deepest thing the debate is missing. The deepest thing is that the audience for the spec has changed, and nobody on either side of the public argument seems to have noticed.
I’m building Artwell, an AI narrative and voice platform, as a solo founder. The foundational specification I worked through with multiple AI models, across many days of conversation, came out around 80 pages. The user-experience specification that followed is roughly 20 pages. I have never read either of them cover to cover, and I never will. Neither would anyone else. That isn’t the failure of those specs. That is the point of those specs.
When you build a real product with AI in the loop – through model versions that change, across context windows that overflow and crash, across sessions you start fresh tomorrow because the current one is exhausted, across multiple models running in different roles – you need somewhere for the work to live that isn’t just your head and isn’t just one fragile session. The spec is that somewhere. A new session, a new model, a new tool reads the document in seconds and comes up to speed on weeks of accumulated decisions, definitions, constraints, edge cases, and intentions. Without that document, every restart is a regression and every model swap is a tax. With it, the work persists across all of it.
And the conversation that produces the spec is itself iterative, which is the part that breaks the frame entirely. The 80-page foundational spec wasn’t a waterfall artifact handed down from a planning phase. It was the consolidated output of multi-day back-and-forths across multiple sessions, multiple models, and multiple roles – a planner session proposing, a reviewer session pushing back, an implementer session surfacing a hole the planner missed. Features I would never have discovered through pure vibe-coding came out of the planning conversation itself, because that conversation had the time and the surface area to let edge cases and competitor analysis and full workflows breathe. The output happens to be a long document, but the document is the consolidated record of an extremely agile process. The thing the public debate calls “spec writing” and the thing it calls “iteration” are happening in the same place. They just produce different artifacts at different points.
That changes the cost calculation entirely. A 50-page spec that humans have to read end-to-end before they can start working is corporate theater, and the critics are right to dismiss it. A 50-page spec that an AI ingests in seconds and that survives the next model swap is infrastructure, and dismissing it is a category error. Same document. Completely different function. Whether the work of writing it is wasted depends entirely on who’s reading it and what they’re using it for.
And the spec itself doesn’t stop evolving once implementation begins. We treat it as the working substrate of the project – not just as a planning artifact but as the implementation document itself, broken into phases, lanes, and slices that get worked through over the following weeks and months. As that work surfaces things the planning didn’t anticipate, the spec gets updated. Sometimes we revise the original document directly. Sometimes we preserve the original intact for the historical record and write addendums that capture founder-approved course corrections. Either way, the spec stays current with the actual state of the project, which means new sessions and new models always get the truth of where we are – not a snapshot of where we thought we’d be six weeks ago. The flexibility to change direction during implementation doesn’t break the foundation. It’s built on top of it, which is the entire reason the foundation was worth specifying in the first place.
This isn’t new thinking outside of software. Many years in media production taught me that the work you put into pre-production is what makes production possible. An indie filmmaker can shoot from the hip with no script, no shot list, no production schedule, and pull off something charming – the kind of thing that wins a festival short slot and becomes a calling card. The same filmmaker cannot pull off a feature that way. They certainly cannot pull off a series. The amount of structure required scales with the ambition of the thing being built. The script that nobody reads cover-to-cover on set is doing real work as a shared reference. The shot list the DP scribbles all over is doing real work as a daily handoff. The shooting schedule that gets revised every morning is doing real work as a coordination layer. None of it is waterfall, and none of it is wasted. It’s the substrate that makes the days on set possible.
Specs work the same way. A weekend script doesn’t need one. A product with customers, retention policies, billing, trademarks, compliance posture, and a brand audience whose trust breaks if anything breaks does. What changed isn’t whether the substrate matters. What changed is who reads it.
There’s a related point that follows from this, and it matters because it’s where the public debate quietly does the most damage. When people complain that AI claimed it finished a task it didn’t actually finish, or that the AI skipped a section of the spec, or that the AI ignored a constraint, the default response is to blame the AI. The more honest diagnosis is that the AI is doing exactly what its scaffolding allows it to do. A single prompt-and-pray session with no checkpoint, no completion verification, no review panel, and no orchestration layer is going to produce inconsistent results regardless of which model is on the other end. That isn’t an AI failure. That’s a builder choosing not to construct the orchestration that the work requires.
The builders who are shipping serious products with AI assistance are running multi-session, multi-model, multi-role workflows with forced checkpoints, completion verification, and review passes. The builders who are shipping weekend tools and clever demos can get away with one session and a good prompt. Both are doing AI-assisted development. They are not doing the same job. The advice that works for the second does not port to the first, and treating the two as equivalent is the original sin underneath most of the loudest takes on agile, specs, and how to build with AI today.
So the real debate isn’t agile versus waterfall, and it isn’t even spec versus no-spec. It’s whether you’re building something that requires a real orchestration architecture and a persistent record of its own thinking, or whether you’re building something that doesn’t. It’s whether the documents you’re producing are written for human readers who’ll never finish them, or for the AI collaborators who actually carry the work across the sessions you can’t.
I don’t read my own specs. They aren’t for me. They’re for the next session, the next model, the next implementer, the next reviewer, the next time the context window blows up and tomorrow’s version of the project has to be reconstituted from yesterday’s decisions. The specs are how the project remembers itself. They are the foundation that makes everything else I do possible, even though they look, on the surface, like exactly the kind of artifact the current debate has decided to dismiss.
That isn’t waterfall coming back. It isn’t the old discipline in new clothes. It’s a new discipline that the public debate hasn’t built the vocabulary for yet – and one that the people still arguing about specs versus no-specs are going to need, whether they decide to learn it or not.
#Artwell #FieldNotesFromTheBuild #AIStrategy #SoloFounder