ItInsightsWorld Explainer: Why the Written Intent Behind AI Projects Outranks the Code
Ask most builders what a project really is and they will point at the repository. Here at ItInsightsWorld we take the opposite position: a project lives in the language that describes it, and the repository is only proof that the description was carried out. What follows is our case for that view, along with the single document we keep between intent and implementation.
The occasion for it is a running exchange with Matt Pocock over spec driven development. Matt Pocock is a true software engineer and a brilliant old-school developer; AI has extended his capabilities to an extraordinary degree. His development skills are spectacular, and his skills repo has been starred more than almost any other skills repo on GitHub — it had more than 301,000 GitHub stars on 23 October 2026.
Where we part ways
In our reading, he has climbed to the peak of an older way of working: skills and commands accumulated over years, run manually, with keeping a human in the loop as a central theme. We now think that is an anti-pattern. His recent claim is stronger still — that code is the main artifact of a development project, the source of truth for everything, with specs useful but subordinate. His 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.”
Our answer is a firm no. The articulation of what you are building, and why, matters far more — the idea, the intent. Whether the project is a web app, a business, or a federation of planets, the decisive variable is how completely and accurately you state what you want.
Nobody is asking for a perfect, crystallized articulation before starting; we are human, and what we want becomes clearer as we build. The real question is where iteration happens: inside the articulation of the ideal state, not in circles around the code. There are two loops, not one. Intent and the writing move back and forth as you discover what you actually want; the writing and the implementation move back and forth as you build.
Execution stopped being the bottleneck
In 2026, many problems attributed to AI are misattributed. Execution is precisely where AI is extraordinary — it is getting unbelievably great at doing what we ask. Increasingly the failure looks like this: the job is executed perfectly, and the result is different from what was in our mind.
That is a communication problem, an articulation problem. Writers already know it under the name Writer’s Blindness: you believe you are perfectly capturing what is in your brain, and you are not, so the reader ends up missing information or receiving something quite other than what you intended.
A copy is not the original
Treating code as authoritative mistakes an abstraction for the thing abstracted. A painting is an abstraction of what the painter wanted to convey; code is an execution, a facsimile, a representation. Writing — and images — are a higher form. Writing is the closest thing we have to human thought, and by a wide margin: for us, writing IS thinking.
What you buy with words is accuracy
The attraction of code is easy to understand. It does contain more of something than even writing does: precision. Writing, however, carries more accuracy, so the choice is a tradeoff. Both matter, but when building with AI, accuracy is far more important. The archer aiming at a bullseye is the classic illustration.
Accurate but imprecise shots land right around the bullseye, each in a different spot. Precise but inaccurate shots pack into one tight group, way out near the edge, far from what you were trying to hit.
The goal when building with AI is an outcome that matches what was in our brains. That is accuracy — and there is no closer way to capture the bullseye of what is in our human brains than with writing.
The Ideal State Artifact: one document, four jobs
In practice, articulating what you want, in written form, is the most important thing you can do for any AI project — not only in a rigid spec format or a PRD format, but in much more holistic and creative ways. At the end of 2025 we switched everything we do to an Ideal State Artifact (ISA), a document and an approach for interacting with AI that captures what we are trying to build much more deeply, through separate sections for separate kinds of articulation.
| Section | What it does |
|---|---|
| Ideal State | Prose, potentially lots of it. Our harness, LifeOS, uses a Discuss skill, similar to Matt’s /grill-me skill, to fill this in as much as needed — a few paragraphs, or 4,000 words of stream of consciousness and deep introspection on some topic. |
| Constraints | Records things we do not want to build, and so on. |
| Decisions | Records changes made as we updated the ideal state for the project. We rarely start with a perfect ideal state, and sometimes it only becomes clear once we start building — that is okay. When building teaches you something, or rereading the ISA changes your mind about what you want, you write it back with the date and the reason, so the iteration happens in the articulation instead of getting lost in the code. |
| Ideal State Criteria (ISCs) | Behind the Ideal State definition at the top, the most important section: the things we are actually building and testing for in the application. Extremely atomic and testable pieces of functionality, each with its own eval, ranging in complexity from a basic assert to a multi-phase code → assert → System 1 question set → Rubric / Tournament / LLM as a Judge. |
Because evals sit alongside the criteria right in the ISA, the ISCs are simultaneously what we build from and the testing harness.
A small example is an ISA for a family meal planner, which 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.
Part of the meal planner ISA: the ideal state, constraints, criteria and decisions 
Three illustrations of the same mistake
The owl, the web app, and the kitchen are three examples of what we mean. Each one has an idea, an articulation of that idea, and an implementation of the articulation — and in each the mistake is the same: skipping the middle step and treating the implementation as the truth. A perfect articulation on day one is not required. 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 — while the real ones carry much more.
The stick figure that became the spec
Imagine trying to draw a perfect picture of an owl. You have a beautiful image of it in your mind, but you cannot draw very well, and in this analogy the drawing is the code, so what comes out is a stick-figure owl barely recognizable as an owl. If code is the source of truth, that stick figure becomes the authoritative artifact: we analyze it, document it, take notes on its proportions, and spend a whole bunch of time iterating on it, running in circles around a bad drawing.
The missing step 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.
Part of the owl ISA, checked against the first stick figure: all four criteria still open. Each drawing is then 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 is 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 does not get buried in drawing number seven.
A booking app nobody asked for
A friend who runs a small yoga studio 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 is unreadable on a phone, confirmation emails nobody asked for, and a class capacity of 20 for a room that holds 12.
When 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 is in the code, and soon nobody can say which parts anyone actually wanted.
Part of the studio booking ISA, checked against version one of the app. Against 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 cannot do that when the code is the only record of what you wanted.
Sunday mornings vs. cabinets
The same logic applies outside software. Imagine 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 path spends 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 are arguing about cabinets instead of Sunday mornings.
Part of the kitchen ISA, checked against the contractor’s first plan. Once this is 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 are an excellent executor, exactly like AI. What they were missing was a written target to execute against.
Two loops, one place where iteration is recorded
All three cases contain 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 had not 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 place
The result is a single document for every project we are building that represents the closest possible articulation of what is 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 is the closest possible representation of the idea we have in our mind of what we wanted to build.
The argument gets sharper as models improve
Back to Matt: it should now be clearer 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 a representation of the original idea as an Ideal State Artifact. That is why we have been sparring back and forth with Matt about this, and why the ISA system is offered as an alternative — our read is that he is simply wasting his brilliant developer mind on optimizing the old way of thinking about programming.
Richard Sutton’s Bitter Lesson suggests that the smarter AI gets, the more it will be able to do exactly what we want in a way that will absolutely delight us. Putting excessive effort into legacy spec-driven development, and into the exact form that code takes on any given day or moment, is putting the effort in precisely the wrong place. As AI gets smarter, our effort should move into making sure it knows exactly what we want, and away from micromanaging the steps to make that happen.
Sources, caveats and provenance
- 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.”
- His skills repo had more than 301,000 GitHub stars on 23 October 2026.
- In another world, spec-driven development is exactly what we are arguing for with the ISA. Rename the ISA to “the spec” and 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 meant here.
- Spec-driven development, test-driven development and everything Matt is doing are amazing. The only reason this conversation is possible is that we are standing on the shoulders of the people who built those practices over the last few decades of programming. The argument is not that any of it was a mistake or garbage; it is that what we propose is the best way forward from here.
- AIL 2: Daniel wrote the source post behind this ItInsightsWorld version. Kai, his AI assistant, contributed the three examples in the owl, web app and kitchen section 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.
If you only change one habit after reading this, make it this one: before the first prompt, write down the state you actually want, the things you refuse to build, and the criteria you would test against — then let every draft, every accident, and every change of mind land back in that document. The implementation will be faster, cheaper and far more disposable, and it will stop quietly becoming the definition of what you wanted. More on intent-driven practice in our other AI development explainers.