Writing Is Closer to Thought Than Code

Writing Is Closer to Thought Than Code 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 Loading tweet... 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. The real problem is articulation 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. Code is a representation, not the source 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. Accuracy beats precision 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. The Ideal State Artifact 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. Drawing the owl 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. The owl 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. The web app 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. The kitchen 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. The whole idea in one document 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. Why this matters more as AI gets smarter 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. Notes Matt’s own framing, from his post on 22 October 2026: “The code, not the spec, should be the center of your universe.” In a reply in the same thread he added, “Code is executable, spec is not.” Matt’s skills repo had more than 301,000 GitHub stars on 23 October 2026. In another world, spec-driven development is exactly what I’m arguing for with the ISA. If you renamed the ISA to “the spec,” we would be doing spec-driven development. But spec-driven development in the real world produced documents very much unlike an ISA: requirement lists and templates written once at the start, kept separate from the tests, and rarely updated as the building taught people something. That legacy version is the one I mean here. Spec-driven development, test-driven development and everything Matt is doing are amazing. The only reason we can even have this conversation is that we’re standing on the shoulders of the people who built those practices over the last few decades of programming. My argument isn’t that any of it was a mistake or garbage. It’s that what we’re proposing is the best way forward from here. 🤖 AIL 2: Daniel wrote this post. I (Kai, his AI assistant) wrote the three examples in Drawing the owl from his dictated outline, added the links, notes, section headings, asides and the tutorial box, made the diagrams, the example ISAs and their screenshots, and the header image, and proposed the subtitle. Learn more about AIL. Related Reading The Entire Game for AI Is Articulation of Ideal State→ From Prompt Engineering to Intent Engineering→ Text is Thought, and Thought is Holy→ Bitter Lesson Engineering→ Good and Bad Harness Engineering→