The ten principles (overview)

A design review reads the ten principles aloud and nobody objects to a single one. Naming judgments sounds right, keeping calculations in code sounds right, evaluating what you built sounds right, so the meeting moves on and spends fifty minutes on which model tier to buy. Six weeks after the feature ships, a household is getting three different answers about whether Tuesday works and nobody can trace any of them to a decision. Every principle was agreed to and not one was checked.

Agreement is cheap because the sentences read like values, and read that way they do no work. A principle earns the name by being specific enough that somebody can hold it against a running system and demonstrate that the system violates it, which is a considerably higher bar than sounding sensible and one that most published advice about building on language models never reaches. All ten of these reach it. Read as a set they state one commitment, the deliberate allocation of judgment, at the ten places where allocation tends to go wrong, which is why the list repays being used to hunt for a violation rather than to collect assent.

Helpful context: Best read after Thoughtware at a glance, which names the parts, and lessons from software architecture, which supplies the engineering parallels. This page is an index. Every principle is argued on its own page, beginning with judgment should be explicit, and designing for the Intelligence Age is the parallel index for product experience.

A principle you cannot fail is a preference

Most advice in circulation about building on language models cannot fail, and "keep your prompts focused" is the clearest case. Two competent engineers can read the same template and disagree about whether it is focused, and neither of them can be shown to be wrong, so the claim can never be improved either. A body of guidance made entirely of statements like that grows without getting better, which is how a team ends up holding a shelf of practices and no discipline.

The ten survive the test, and the way each one survives is worth confirming once rather than assuming. Ask whether cognitive capability is encapsulated and the answer sits in the call sites, because either callers depend on a stated responsibility and result shape or they reach into template text, and somebody can open the file and look. Ask whether evaluation belongs to the architecture and the answer is whether cases exist bound to the named judgment, or whether quality is still an impression collected after release. Neither question turns on taste, so these are obligations rather than values, and a review that produced ten nods tested none of them.

Being individually checkable is what makes the list usable. Being related to each other is what makes it a set.

Five of them are a spine

Five of the ten sit in a dependency order, running 01, 02, 03, then 06 and 08, and skipping one of those does not leave a gap so much as disable everything downstream of it. Judgment should be explicit comes first, because nothing can be placed until it has been named. Locality comes second, because a named decision still has to be handed to the smallest component capable of owning it. Encapsulation comes third, because a decision with a home can then be depended on through its contract while the mechanism underneath it changes freely.

The fourth and fifth stages are the ones teams reach last and need most. Evaluation belongs to the architecture because a contract on its own states what was promised and nothing about what happens, and the boundary drawn at stage three is precisely what a set of cases can attach to. Maturity is the fifth stage, and it takes settled work out of runtime deliberation because once evidence shows a judgment has stabilised, the same boundary that made it measurable makes it movable, into a rule, into deterministic code, or into a named skill with a route back to deliberation when the assumptions break.

Read forward, the spine explains why the early principles feel abstract, since they are the ones whose payoff arrives two stages later. A team that draws contracts without naming has encapsulated a decision nobody located, and it finds out when the first failing case cannot be assigned to any judgment. That is the diagnostic worth having: a failure at the first stage presents as a failure at the fourth, so the repair usually belongs earlier than the symptom.

Four of them are fences

The remaining obligations do not extend the spine, they bound it, and each one names something judgment is not allowed to absorb. Three of them face outward, 04, 07, and 10. Procedure is the first. Determinism should remain deterministic, so calculation, permission, persistence, and exact validation keep the certainty already available to them instead of acquiring variance nobody asked for. Permission is the second. Authority must be designed separately from capability, so being able to determine something confers nothing whatever about being allowed to act on it. People are the third. Human judgment remains part of the system, deliberately located, rather than admitted reluctantly as evidence that automation fell short.

The fourth fence, 05, points inward at the agent. Agents should own goals and not every judgment or procedure, which is the same refusal aimed at a runtime loop, so recurring judgments stay separable, stable procedures get packaged, and the agent spends its reasoning on what genuinely remains unresolved. Collapse all four fences into one general reasoning loop and the monolithic model box is back, this time with a vocabulary attached.

Fences fail by omission, which is what makes them harder to hold a system to than the spine. A missing boundary throws no error and leaves no gap on a diagram, so a demo where nobody asked the product to spend money looks identical to a demo where the product was never permitted to. Checking a fence therefore has to be adversarial: name the exact operation, ask what stops it, and treat "nobody has tried" as a failing answer.

The objective is not to maximise autonomy or the amount of AI inside a product. Thoughtware becomes dependable when cognition itself becomes architected.

Thoughtware White Paper · §13

Principle nine is about the other nine

One of the ten makes no claim about a system's structure at all. Architecture should outlive implementation vocabulary is a claim about the other nine, asserting that the answers they produce should still mean something once the models, prompting techniques, retrieval methods, and orchestration frameworks underneath have all been replaced. That is why every one of them is worded in terms of judgment, responsibility, authority, context, and evaluation rather than in terms of whatever this year's tooling happens to call those things.

The test is quick and uncomfortable. Describe what your system is responsible for without naming a vendor, a framework, or a technique, and if the description collapses, the failure is the one why the words we have fail sets out, and the other nine principles have nothing left to attach to. Architecture outlives implementation vocabulary argues the principle itself, and category, not mechanism settles why the category words are the durable ones.

One principle held against a running system

Locality is the easiest of the ten to check, so it makes the best drill, and it is also among the most frequently broken. The household says Tuesday is busy, which is context for this run and nothing more. Whether a particular stir-fry fits Tuesday is an open judgment, so it has an owner: AssessMealPracticality takes the evening's constraints and a candidate meal and returns a fit assessment with its assumptions visible. Holding the principle against the system then takes one question, which is where else that same fit decision gets made.

When the honest answer names the chat surface deciding whether to warn the household, the planner deciding to place the meal anyway, and the shopping list assembler quietly buying for it, the violation stops being an opinion, because you can point at three places that will disagree in production. Where does a decision live works through what the disagreement costs a household. The shape of the question transfers to every row of the table below: pick one operation, ask where it is decided or what stops it, and see whether the system can produce a single answer.

Where each principle is argued

Each of the ten has a page that argues it rather than restating it, and the arguments are where the qualifications live, which is the part any summary loses first. The table is a directory and carries no teaching on purpose, since a principle you can recognise in one line is some distance from a principle you can apply.

#	Principle	Where it is argued
01	Judgment should be explicit	Judgment should be explicit
02	Judgment should have locality	Judgment should have locality
03	Cognitive capability should be encapsulated	Encapsulation
04	Determinism should remain deterministic	Closed decisions belong in code
05	Agents should own goals, not every judgment	Agents own goals
06	Evaluation is part of architecture	Evaluation is part of architecture
07	Authority must be designed separately from capability	Authority is granted
08	Maturity moves settled work out of runtime deliberation	Maturity moves settled work out
09	Architecture should outlive implementation vocabulary	Architecture outlives vocabulary
10	Human judgment remains part of the system	Human judgment remains

The same discipline appears at the cognitive unit layer as twenty-three statements rather than ten, and the difference is grain rather than disagreement. Where the White Paper says cognitive capability should be encapsulated, the cognitive unit book works out which artifacts constitute the boundary and what makes two implementations the same judgment. It also sorts its statements by kind, separating the few that are close to absolute from the ones that price a trade you may reasonably want to make and the ones that only describe how the material behaves, and that habit is worth importing here. Not every row above is the same sort of claim, so reading all ten as flat instructions is what produces the meeting where everybody agrees and nobody checks.

What to do next

A useful pass over a shipping feature runs in the order the spine gives, asking what judgment is named, where it lives, what its callers depend on, which cases bind to it, and what has stabilised enough to leave runtime deliberation. The fences come after that, one named operation at a time, asking what stops each one rather than whether anybody has tried it yet.

A failing answer anywhere is worth a design pass before the next model conversation, and the ordering tells you where to spend it, because a failure early in the spine tends to present as a failure late. Passing answers expire too, since endorsing new knowledge, granting new authority, or letting a provider swap an engine underneath you all change what these questions return.

Read next: Open, closed, and closing starts the Decisions track with the two questions that sort a single decision, which is the work the first principle assumes has already been done.