Writing Is Closer to Thought Than Code
Based on Daniel Miessler's article
https://danielmiessler.com/blog/writing-is-closer-to-thought-than-code

00:00:00 — The app works. The idea got lost.

Imagine asking an AI to build a family meal planner. It produces a polished app. The buttons work, the tests pass, and the calendar fills with dinners. But your family still argues about food.

The software runs. Yet the experience you wanted never arrived. Daniel Miessler's article, Writing Is Closer to Thought Than Code, asks us to examine the gap between the idea in our heads and the instructions we actually give.

In this lesson, you will learn his argument, build a small Ideal State Artifact, and connect its criteria to evaluations. The aim is not better sounding prompts. It is a clearer target for the work.

00:00:41 — Two meanings of “source of truth”

Miessler frames his argument as a disagreement with developer Matt Pocock. In the position he quotes, code belongs at the center because code is executable. Specifications help, but the implementation is the main artifact.

Miessler instead puts articulated intent at the center: what are we building, for whom, and why? His claim is that this is a higher fidelity record of the original idea than the code that happens to implement it today.

A useful distinction is this: code tells us what the system actually does. Written intent tells us what we want it to accomplish. The article argues that the second question should direct the first, especially when AI does the implementation.

00:01:25 — Thought → writing → implementation

Picture three stages. First comes thought: a parent imagining a calmer Sunday evening. That intention contains context, feelings, priorities, and tradeoffs. None of those automatically reach the AI.

Second comes articulation. Writing, and sometimes images, make the intention available outside your head. Miessler treats writing as closest to thought. In his model, it is the first representation; code is another step removed.

Third comes implementation. The same desired experience could produce different databases, interfaces, or programming languages. Those choices matter, but they are means. If the means change, we still need a stable explanation of the end.

00:02:11 — The missing requirement was in your head

Why is articulation difficult? The article points to writer's blindness, also called the curse of knowledge. Once you know the context, it becomes hard to notice what a reader does not know.

You think, obviously the meal planner must avoid peanuts. But your prompt only says, make a weekly meal planner. The missing allergy requirement feels obvious to you because you already carry it in your mental model.

Miessler argues that many apparent AI failures are actually communication failures. Treat that as a diagnostic question, not a universal excuse: was the requirement absent, misunderstood, or implemented incorrectly? Those are different failures with different fixes.

00:02:54 — Accuracy is not the same as precision

The article uses archery to explain the distinction. Accuracy is closeness to the bullseye. Here, the bullseye means the outcome the person actually intended. Shots can be near that target without landing in exactly the same place.

Precision is a tight grouping. A program can implement a very exact rule while that rule serves the wrong goal. Think of a planner that perfectly minimizes calories when the family really wanted less stress at dinner.

Miessler associates writing with accuracy and code with precision. This is an analogy, not a guarantee about either medium. Vague prose can miss the goal too. The practical lesson is to establish the right target, then demand reliable implementation.

00:03:40 — The Ideal State Artifact

Miessler's proposed working document is an Ideal State Artifact, or ISA. It is more than a rigid specification. It begins with prose that captures the desired state as fully as the problem needs.

It also records constraints: things we must not do. And it records decisions, including choices made while the goal becomes clearer. The article explicitly allows understanding to evolve as we build. You do not need perfect foresight.

Finally come Ideal State Criteria, or ISCs: atomic, testable pieces of functionality, each paired with an evaluation. The artifact holds the vision, its boundaries, and the checks that connect that vision to a real implementation.

00:04:26 — Start with the Sunday-night experience

Now apply the article's example. The ideal state is a Sunday evening where the family chooses a week of dinners in under five minutes, everyone is excited to eat them, and the groceries are already in the cart.

Notice what this gives us that build a meal planner does not. We have a person, a situation, a time budget, an emotional outcome, and a completed task. A calendar screen alone does not satisfy that description.

As a practical extension, ask the AI to interview you about gaps. What does excited mean for this family? Which grocery service? Who approves substitutions? The purpose of discussion is to expose missing context, not decorate the document with extra words.

00:05:10 — Boundaries and decisions do different jobs

The example's first constraint is no peanuts, because Maya has an allergy. Its second is that weeknight dinners take forty minutes or less. These are boundaries that candidate plans must respect.

The decisions section explains why calorie tracking was dropped: it made planning feel like a chore. That rationale matters. Otherwise, an AI or a future collaborator might reintroduce the feature, believing more functionality must be better.

A safety caveat for this teaching example: checking ingredient names is not a complete allergy safety system. Labels, substitutions, and cross contact require attention too. Use the example to understand the structure, not as clinical guidance or a production safety design.

00:05:57 — Turn the vision into checkable criteria

The article breaks the planner into five criteria. No planned dish contains peanuts. The grocery list covers every ingredient. Every weeknight dinner takes forty minutes or less. These are the first three checks.

The fourth asks whether a ten year old would want to eat each dinner. The fifth asks whether the week feels varied rather than repetitive. Now we can see a difference between mechanical checks and judgments about the experience.

Keep each criterion narrow enough that failure tells you something useful. Grocery completeness and dinner variety should not share one pass or fail box. They can fail independently, and the system needs different changes to improve each one.

00:06:40 — Match the evaluation to the claim

For a deterministic claim, use a deterministic check when the data supports it. Compare required ingredients with the grocery list. Check recorded preparation times against the limit. An assertion is only as meaningful as the data and assumptions behind it.

For kid appeal, the article proposes a question set. As an instructional example, ask about familiar flavors, difficult textures, and whether the family has actually liked similar dishes. A model's answer is evidence to inspect, not the child's own preference.

For variety, use a rubric or a model judge. Define dimensions, such as repeated main ingredients, cooking methods, and flavors. Miessler describes evaluations ranging from basic assertions to multi stage processes and model judges. Choose the simplest evaluation that really tests the claim.

00:07:34 — One criterion, two directions

Here is the article's strongest structural idea. The criteria tell the AI what to build, and the evaluations tell us whether it succeeded. They are not separate stories about the project. They share one definition of success.

Take grocery completeness. That criterion drives recipe expansion and list generation. Its evaluation then compares the ingredients required by the plan with the list the system actually produced. If garlic disappears during aggregation, we have a specific failure to investigate.

This does not mean prose executes itself. The checks still need to be implemented and run. The value is traceability: for each behavior, show the intention it serves and the evidence that it meets that intention.

00:08:21 — Let evidence improve the ideal state

Now imagine all five example criteria pass, but a parent needs twelve minutes to finish planning. This is an instructional extension, not an outcome reported in the article. What did our checklist miss?

The ideal state promised under five minutes, yet the five listed criteria never directly tested that promise. This is why a passing checklist cannot prove that the entire vision has been captured. Compare the criteria back to the prose.

Add a timed planning task under stated conditions, observe representative users, and investigate the friction. If the goal itself changes, update the ideal state and record the decision. The document should learn from use rather than become a frozen contract with reality.

00:09:07 — Smarter execution shifts the human job

Miessler's broader prediction is that, as AI becomes better at execution, the scarce human contribution shifts toward telling it exactly what we want. He argues against keeping humans in every implementation step by default.

He invokes Richard Sutton's Bitter Lesson: general methods that benefit from more computation tend to beat approaches built around handcrafted cleverness. Miessler applies that lesson to development, favoring clear goals over detailed micromanagement. That application is his argument, not a proof that all supervision is wasteful.

Our practical caveat is to separate direction from permission. An AI can choose implementation details without being allowed to spend money, release sensitive data, or deploy unsafe changes. Clear intent should reduce unnecessary steering, not remove accountability for high stakes actions.

00:10:02 — Your turn: write a small ISA

Pause and apply this to a real project. Without looking back, write one paragraph describing the ideal experience. Name the person, the situation, and the change they should notice. Avoid starting with a technology stack.

Then add two constraints and one decision with its reason. Write three narrow criteria. Beside each, specify how you would check it: an assertion, a real user task, a question set, or a rubric. Pause the video now and try it.

When you return, test your understanding. If every criterion passes, could the person still be disappointed? If yes, identify the missing expectation. If your only evaluation is ask the AI whether it did a good job, replace that with observable evidence.

00:10:50 — Capture the target. Then prove the outcome.

Here is the lesson in one chain. Articulate the desired state. Make its boundaries and tradeoffs visible. Translate it into atomic criteria with evaluations. Build, observe, and revise what the evidence shows was incomplete.

Miessler's central claim is not that code has no value. It is that code is a representation of a goal, and written intent is closer to that goal. The implementation should serve the idea, not silently replace it.

This is an independent educational adaptation of Daniel Miessler's article, published October twenty third, twenty twenty six. The narration is synthetic. The diagnostic questions and safety caveats are teaching additions. Before your next AI build, ask: have I described the target, and what evidence would show we actually reached it?