I’ve been having an almost-debate with Matt Pocock for a while about the best way to do spec driven development.
Matt is a brilliant old-school developer: a true software engineer. And he’s been using AI to enhance his capabilities to an extraordinary degree. His development skills are spectacular, and have been starred more than almost any other skills repo on GitHub.2
So what’s my disagreement?
Basically I think he is at the top of the mountain for the old way of doing things. He’s got tons of skills and tons of commands that he encourages people to run manually. Having a human in the loop is a major theme for him, which I think is now an anti-pattern.
But his central idea lately has been that the most important thing in a development project is the code itself. That specs are useful and everything, but the code itself is the main artifact. The source of truth for everything.1
I disagree strongly. I think the articulation of what you’re building, and why, is far more important. Basically, the idea. Your intent.
I think the most important thing in any project you’re building with AI (and even without it), from building a web app, to starting a business, to managing a federation of planets, is how completely and accurately you articulate exactly what you want.
To be clear, I’m not saying you need a perfect, crystallized articulation before you start. Nobody has that. We’re human, and what we want gets clearer as we build. My argument is about where that iteration happens: inside the articulation of the ideal state, not in circles around the code. And there are two loops, not one. Your intent and the writing go back and forth as you figure out what you actually want, and the writing and the implementation go back and forth as you build.
I think most of the problems we see with AI in 2026 are misattributed. AI is extraordinary at execution. It’s getting unbelievably great at doing what we ask it to do. More and more of the problems at this point are it executing the job perfectly, and having the result be different than what was in our mind.
But this is a communication problem. It’s an articulation problem.
Authors have this same problem. It’s commonly called Writer’s Blindness. It’s where you think you’re perfectly capturing what’s in your brain, but you’re not. And so the receiver, or the reader, ends up missing information or getting a completely different review than the author intended.
The problem with Matt’s position is that he thinks code is authoritative. It’s actually an abstraction, the same way a painting is an abstraction of what the painter was wanting to convey. It’s an execution. A facsimile. A representation.
But there’s a higher form of this, and that’s writing. And images.
Writing is the closest thing we have to human thought. As I like to tell people all the time, for me writing IS thinking. It’s the closest thing we have, by a wide margin.
But I get why Matt is enamored with code. It does have more of something than even writing, which is precision. Writing has more accuracy, though. So it’s a tradeoff between accuracy and precision.
We obviously want both, but when it comes to building stuff with AI I think accuracy is far more important. The classic illustration of this is an archer trying to hit a bullseye on a target.
So accuracy without precision is a bunch of shots that all land right around the bullseye, but each in a different spot. Precision without accuracy is the opposite: every shot packed into one tight group, but way out near the edge, far from what you were trying to hit.
When we build with AI we want the outcome to match what was in our brains. That’s accuracy. And there’s no closer way to capture the bullseye of what’s in our human brains than with writing.
So what does that mean?
It means articulating what you want, in written form, is the most important thing you can do for any AI project. And I don’t mean just in a rigid spec format, or a PRD format, but in much more holistic and creative ways.
I figured this out at the end of 2025 and switched everything I do over to something called an Ideal State Artifact (ISA), which is a new document and approach for interacting with AI. It’s a much deeper capture of what we’re trying to build, and it uses multiple sections for the different types of articulation.
There is the articulated Ideal State, which is prose. Potentially lots of it. My harness (LifeOS) uses a Discuss skill (similar to Matt’s /grill-me skill) to help fill this in as much as needed. This can be a few paragraphs, or it could be 4,000 words of stream of consciousness and deep introspection on some topic.
Then there are Constraints, things we don’t want to build, etc. Then there are Decisions that were made as we updated the ideal state for the project. We rarely start off with a perfect ideal state in the beginning. Sometimes it only becomes clear as we start building, and that’s ok. That’s exactly what the Decisions section is for. When building teaches you something, or rereading the ISA changes your mind about what you want, you write it back into the ISA with the date and the reason, so the iteration happens in the articulation instead of getting lost in the code.
And then the most important section (behind the ideal state definition at the top) are what we call Ideal State Criteria (ISCs). These are things we’re actually building and testing for in the application. They are extremely atomic and testable pieces of functionality. Each one of them has its own eval associated with it as well, which can range in complexity from a basic assert
to a multi-phase code
→ assert
→ System 1 question set
→ Rubric / Tournament / LLM as a Judge
.
What’s really powerful about the Ideal State Criteria being defined this way, with their evals defined along side them right in the ISA, is that the ISCs are simultaneously what we build from AND the testing harness!
Here’s a small example, an ISA for a family meal planner. This shows only a piece of it. A real ISA also carries the full ideal state articulation, a test strategy, the evals themselves and a running status.
Here are three examples of what I mean. Each one has an idea, an articulation of that idea, and an implementation of the articulation. And in each one the mistake is the same: skipping the middle step and treating the implementation as the truth.
None of these examples needs a perfect articulation on day one. You write down what you can, you build, and the drafts teach you what you forgot to say. Reading what you wrote also changes what you want. The difference is that both kinds of lesson go back into the ISA. Each ISA below is also just a slice, the ideal state and the criteria. The real ones carry much more.
Say you want to draw a perfect picture of an owl. You have this beautiful image of it in your mind. But you can’t draw very well, and in this analogy the drawing is the code. So what comes out is a stick-figure owl that’s barely recognizable as an owl.
In the code-is-the-source-of-truth version, that stick figure is now the authoritative artifact. We analyze it, document it, take notes on its proportions, and spend a whole bunch of time iterating on it. We’re running in circles around a bad drawing.
What we skipped was the clean translation from the brain to a captured state, using the most precise tool we have for that, which is writing. That written description is the thing the drawing is trying to implement.
Now every drawing gets checked against the ISA instead of against the last drawing. The stick figure fails all four criteria, and the next attempt knows exactly what it’s aiming at. And if a draft makes you realize you actually want the owl in flight, that goes into the ISA as a Decision. It doesn’t get buried in drawing number seven.
A friend runs a small yoga studio and wants her regulars to book classes without texting her. Someone gives an AI a one-line prompt, and it builds a booking app with a login wall, a calendar grid that’s unreadable on a phone, confirmation emails nobody asked for, and a class capacity of 20 for a room that holds 12.
If the code is the source of truth, that app is now the spec. Tests get written for the calendar grid. The login flow gets documented. Somebody refactors the email system. Every accident in version one becomes a requirement because it’s in the code, and soon nobody can say which parts anyone actually wanted.
With the ISA, the login wall fails ISC-1 and the wrong capacity fails ISC-2, so both go. Nobody writes tests for the calendar grid, because no criterion asks for one. And the code becomes disposable. If version one is bad enough, you throw it out and rebuild against the same ISA, and the same evals check the new build. You can’t do that when the code is the only record of what you wanted.
This works outside software too. Say you’re remodeling your kitchen. The idea is Sunday mornings: two of you cooking, friends on stools at the counter, everyone in one conversation. You give the contractor a rough sketch, and they build it with the stove facing the wall, so whoever is cooking has their back to everyone.
The implementation-first version is spending the next three months adjusting what got built. You move a cabinet, swap the hood, measure everything and document the room as it stands. Now you’re arguing about cabinets instead of Sunday mornings.
With this written down, the stove-against-the-wall plan fails ISC-1 on paper, before anyone cuts a single board. The contractor was never the problem. They’re an excellent executor, exactly like AI. What they were missing was a written target to execute against.
In all three cases there are two useful loops, and the ISA sits in the middle of both. In the first, your intent and the ISA shape each other: you write down what you want, reading it back shows you what you actually meant, and the ISA changes. In the second, the implementation gets checked against what you wrote, and what you wrote gets sharper every time a draft shows you something you hadn’t said yet. Iterating is normal and good in both. The ISA is simply where the iteration gets recorded, in the ideal state, the criteria and the Decisions log.
So what we end up with is a single document for every project we’re building that represents the closest possible articulation of what’s in our mind. We call it an Ideal State Artifact because the ideal state articulation at the top is the most important thing, but really the entire document represents the closest possible representation of the idea we have in our mind of what we wanted to build.
Now, returning to Matt, it should be much clearer now why source code for the implementation of this project, in some computer-friendly language like Typescript or Python or whatever, is nowhere near as high-fidelity of a representation of the original idea as an Ideal State Artifact.
So this is why I have been sparring back and forth with Matt about this, and trying to offer the ISA system as an alternative. I think he’s simply wasting his brilliant developer mind on optimizing the old way of thinking about programming.4
What we should all take from Richard Sutton’s Bitter Lesson is that the smarter AI gets the more it’ll be able to do exactly what we want in a way that will absolutely delight us.
Over-rotating on legacy spec-driven development, and the exact form that code takes on any given day or moment, is putting the effort in precisely the wrong place.3
The smarter the AI gets the more we should move our effort into making sure it knows exactly what we want. And less into micromanaging the steps to make that happen.