Lessons from software architecture

The Meal Companion's first implementation is one large cognitive procedure. Inside a single boundary it interprets the request, identifies constraints, recalls household preferences, chooses meals, assesses practicality, arranges the week, checks variety, notices ingredient waste, explains its choices, decides whether to ask a question, and revises after correction. The plans it returns are often good, and then a household rejects Tuesday as impractical and nobody on the team can say which of those eleven jobs went wrong, because all eleven happened in the same place.

Any engineer who has maintained a large codebase recognises the shape of that, since it is the thousand-line function with a different material inside it. Software engineering answered the problem by dividing computation into functions, gathering related responsibilities into modules, separating what a component promises from how it delivers, and attaching tests to the promise. Reaching for the same answer here is the right instinct, and the analogy repays it unevenly.

What transfers intact is placement: where a responsibility lives, who owns it, and what callers are allowed to depend on. What does not transfer is the way architects knew a change was safe, because code review, the diff, and swapping one implementation for another on a signature match all rested on being able to read the implementation and see what it did. The mirror hands over the placement discipline whole and hands over none of the verification, so every borrowed habit arrives here needing an evidence artifact it never needed in deterministic code.

Helpful context: Where does a decision live introduces locality and what is Thoughtware names the category. Encapsulation develops the contract discipline in the cognitive unit track. This page draws the parallel and marks where it stops.

Software gave complexity places to live

Software engineering never removed complexity from large systems, and its actual achievement was to create locations for complexity to sit. Functions located transformations, modules located ownership, interfaces located promises, processes located running work, and tests located expected behaviour. Every one of those answers the same question, which is where a given responsibility lives, and answering it is what stops a change in one place from having effects somewhere unrelated, so the discipline was never really about elegance. The oversized planner answers that question nowhere, since interpretation, candidate production, practicality, composition, and critique are five responsibilities sharing one address.

The correspondence runs past decomposition into the structures teams argue about later. A library of cognition plays the role a shared package plays, making a capability available beyond the place it was first written. An agent definition sits closer to a module, since it imports capabilities, carries policy, and coordinates work toward a goal, while one agent run is the process instance with its own working state. Losing that last distinction costs what it costs in ordinary software, because a correction made for this week then leaks into next week's behaviour and a paused plan loses its progress.

The pairings are worth having in one place, and the reason to hold them loosely sits in the right-hand column, where every entry has acquired something its counterpart never needed.

Conventional software	Thoughtware correspondence
Function	Cognitive unit owning one bounded judgment
Shared package	Library of cognition with contracts and evaluation records
Module	Agent definition with policy, authority, and stopping conditions
Process instance	One agent run carrying its own working state
State machine	Agent loop whose transitions are themselves decided by judgment
Automated tests	Evaluation suites plus trajectory checks
Optimised hot path	Compressed loop behind an applicability guard

The last row is the one already developed in deliberation and automaticity, where a fast path stays legitimate only while its guard holds. What the whole table has in common is that every row answers where something goes.

What the mirror does not reflect

None of it answers how you know the thing in that location works, and in deterministic software nobody had to ask separately. The implementation was the description. A reviewer read the body, and the reading was what licensed the merge, which is why code review has carried so much of the weight of confidence for so long. A template offers nothing comparable, because it records what was asked for and says little that is dependable about what comes back. Reading a template records a hope sets that guard out for architects.

That single fact is what makes the borrowing uneven. Placement never depended on reading the implementation, so it arrives here undamaged. Confidence depended on reading entirely, so every instrument built on top of it has to be rebuilt around a record of measured behaviour attached to the thing that was measured.

The analogy tells us to divide, name, compose, version, test, and improve. Each of those disciplines must then be reinterpreted for judgments whose outputs are variable and context-sensitive.

Introduction to Thoughtware · Ch. 16

Every borrowed instrument gets rebuilt around evidence

The rebuilding starts at the interface, because that is where software put everything a caller was entitled to know. A signature named types and operations, and anything further a caller wanted could be recovered by reading inward. A cognitive contract has to carry what reading would have supplied: what information the judgment expects, what it returns when that information is absent, which assumptions it made on the way, and the criteria under which an answer counts as good. None of that is ornament, since a caller who cannot see it has no basis for deciding how far to trust the answer it receives.

Tests move in the same direction and for the same reason. A deterministic test compares a result against one expected value, which works because exactly one value is correct. Several weekly plans can satisfy the same household while differing in almost every cell, so the test for AssessMealPracticality names a case, a rubric, and a threshold instead, and those three stay explicit even where a single right answer does not exist. Trajectory checks appear one level up on the same logic, asking whether the loop repaired a rejected meal locally rather than regenerating a week the household had already accepted.

The version number moves last and moves furthest. Swapping the model while the evaluation cases still pass changes nothing about the judgment, so callers need no new version and should not be given one. Adding twenty cases changes no behaviour whatever and does need a version, because a published figure describes performance on a set of cases and the set is now a different set. What a judgment's identity is made of is worked out in cognition as material, and the point worth carrying out of the mirror is narrower: the number tracks the evidence rather than the code, which no package manager has ever asked anyone to accept.

Refactoring is where the divergence bites

Extraction is the move the oversized planner needs, and refactoring is the borrowed discipline that suffers most on the way over. In software a refactor changes internal structure while preserving external meaning, and a team can believe it worked because the compiler, the test suite, and a readable diff all agree with each other. Two of those three are unavailable here.

A cognitive refactor can preserve every input and output shape and still move the standard of judgment being applied. Pulling practicality assessment out of the ComposeWeek template can leave the fields identical and yield a judgment that is more cautious, more agreeable, or more willing to challenge than the paragraph it came from, and no schema records the difference. So whether the refactor preserved intent becomes a behavioural question: the cases the old arrangement passed have to keep passing, and the conduct the product promised has to survive the split.

Which reverses the order of the work. Cases get written before the prose gets moved, since an extraction with nothing behind it cannot be told apart from a rewrite, and evidence dies when the template changes traces what happens to teams who learn that afterwards.

What this looks like in practice

The first refactor of the Meal Companion can be named completely, and naming it is most of the work. Interpretation separates from planning as InterpretWeek, candidate production becomes GenerateCandidates rather than sharing a boundary with ComposeWeek, practicality gets its own judgment in AssessMealPracticality, criticism moves into CritiquePlan, and forming a question becomes AskTargetedQuestion, kept apart from the decision about whether asking is warranted at all. Exact allergy enforcement and portion arithmetic leave cognition for deterministic code, while the agent keeps the weekly outcome it always owned. None of that is unfamiliar to anyone who has pulled repositories out of controllers, so the temptation is to stop there.

Stopping there buys eleven addresses. What makes it a refactor is what each piece carries out with it, because the address is worth nothing until something can fail at it. AssessMealPracticality leaves with cases saying that an hour of active effort on a flagged evening has to fail and that one accepted leftover night has to pass, so a later engine swap turns into a comparison rather than a matter of taste. CritiquePlan leaves with trajectory cases asking whether a rejected Thursday got patched or the whole week got rebuilt underneath it.

The Tuesday question then becomes ordinary. An impractical Tuesday is either a failure in AssessMealPracticality, which its cases should have caught and can be extended to catch, or a failure in ComposeWeek, which ignored an assessment that was right. Intelligence beneath the surface is what that settlement feels like from the household's side, where a product that has stopped arguing with itself reads as structure rather than as an absence of intelligence.

What to do next

The productive exercise on an existing product is to take a service boundary you already trust and list the judgments still living inside it as conditional prose or template paragraphs. Extract the one that has already caused a production argument, because the argument supplies the first evaluation cases and the extraction is easiest to justify while the pain is recent.

Decomposition is the part of this that architects already know how to do, and it is not where the difficulty sits. The unfamiliar work is writing down what good enough means under the contract, plainly enough that a colleague could read it and disagree with it.

Read next: The ten principles (overview) reads the recurring obligations as one set rather than as ten separate rules.