In 1962, Herbert Simon published a paper about why complex systems in nature are almost always hierarchical. It is a paper about proteins, economies, tissues and social organisations, and it opens its section on evolution with a parable about two watchmakers.

“There once were two watchmakers, named Hora and Tempus, who manufactured very fine watches. Both of them were highly regarded, and the phones in their workshops rang frequently — new customers were constantly calling them. However, Hora prospered, while Tempus became poorer and poorer and finally lost his shop. What was the reason? The watches the men made consisted of about 1,000 parts each. Tempus had so constructed his that if he had one partly assembled and had to put it down — to answer the phone say — it immediately fell to pieces and had to be reassembled from the elements. The better the customers liked his watches, the more they phoned him, the more difficult it became for him to find enough uninterrupted time to finish a watch.”¹

Hora built the same thousand-part watch differently. Subassemblies of about ten elements each; ten of those making a larger subassembly; ten of those making the watch. When his phone rang, he lost only the piece in his hand.

Notice the detail most retellings drop. Both watchmakers were excellent, and both were in demand. The phone rings because the work is good. Tempus is not being punished for incompetence, or for laziness, or for failing to concentrate. He is being punished for architecture, and the better he gets at his craft, the more the architecture costs him.

Simon does the arithmetic

What makes the parable more than a fable is that Simon works it out. Suppose the probability of an interruption while adding any one part is p. Tempus finishes an uninterrupted watch with probability (1−p)^1000; Hora completes any one subassembly with probability (1−p)^10. Set p at one in a hundred and the gap is not marginal.

Simon’s conclusion is one sentence, and it is the sentence the rest of this book is a commentary on:

“Complex systems will evolve from simple systems much more rapidly if there are stable intermediate forms than if there are not.”¹

The phrase doing the work is stable intermediate form. It does not mean “smaller piece”. Plenty of small pieces are useless on their own. It means a piece that survives being put down — one that is still a thing when you come back to it, rather than a heap of components that happened to be adjacent when the phone rang.

Now ask what an agent’s working life is like

Here is where a paper about protein folding becomes an architecture memo.

Context windows fill and end. Sessions die. Compaction eats the middle of the history in the middle of a task. The next agent that picks the work up starts cold, with your repository in front of it and none of yesterday’s reasoning behind it.

That is the whole argument. Everything after it is mechanism.

And it changes what kind of claim decomposition is. As long as the justification was “smaller things are tidier”, decomposition sat in the same drawer as consistent naming and good commit messages: virtues, genuinely useful, and the first thing dropped under deadline. Every engineer has shipped the nine-hundred-line file and promised to split it later.

Decomposition is how work outlives the worker — and your workers die every hour.

Once that is the framing, “we’ll modularise later” stops being a trade-off and starts being a defect you chose. You are not deferring tidiness. You are electing to hold a thousand parts in your hands in a workshop where the phone never stops.

How this was actually found

Worth being honest about the order of discovery, because it is the credential rather than a confession. Nobody read Simon and then went looking for applications.

The practice came first, from years of ordinary software habits carried into a new kind of work:

“Another pattern I just realised: break things into components. Obviously I’ve been doing it forever in code — you don’t write one big monolithic chunk, you break it into functions and classes and refactor it different ways.”

Then prompts pulled out of agentic code into their own markdown files, so they were separately maintainable. Then a thousand-line file that early coding models could not edit without damaging. Then an ebook built as one markdown plan per chapter, one PHP file per rendered chapter, and an include to put them back together. Then a wiki whose pages behaved suspiciously like functions.

Four different materials. One shape. And the moment of recognition:

“The real point I’m making is that I made it composable, and AI could reason over it better — focus on one bit at a time, then pull it together. And believe it or not, I think that’s what the wiki is doing too: making a really complex thing composable and navigable. So perhaps decomposing, making navigable, and recomposing is an agentic pattern.”

All three moves are in that sentence. Decompose. Make navigable. Recompose. The third one arrived in the same breath as the other two and then got ignored for a year, which turns out to be the most consequential omission in the whole pattern. Chapter 8 is about nothing else.

What this book is

A pattern with four moves, running on five surfaces, with the scarce judgment in the cut.

• Part I establishes why the pattern exists and why it did not expire when context windows grew. The mechanics of agent mortality are Chapter 2; the six jobs a single component does at once are Chapters 3 and 4.
• Part II is the mechanism, move by move: how to choose the unit, what an interface is for, what the map must be, and why assembly has to be stupid.
• Part III runs the same cut on five surfaces — code, artifacts, agents, knowledge, and the question itself — including one worked example you can inspect, because it is the document you are currently reading.
• Part IV is the hard part: the boundary condition, three tests for a cut line, what the pattern costs, where it stops paying, and what to do on Monday.

What it is not: a chunking guide, a framework comparison, or an argument that models are weak. Models are extraordinary and getting better weekly. That is precisely why the parts of your system that are not the model deserve more attention than they get.

The next chapter takes the phone off the wall and looks at how it actually rings — because “the model forgets” is folklore, and folklore does not tell you what to build.

A session ends mid-sentence. You come back the next morning, open a fresh one, and the agent greets you as a stranger — with your repository in front of it and none of yesterday’s reasoning behind it. It does not know which approach you rejected on Tuesday, or why the module is named what it is named, or that the obvious fix was tried and abandoned.

Nothing broke. That is the designed behaviour of the system.

Chapter 1 asserted that interruption is the agent’s operating condition. This chapter makes it mechanical, because “the model forgets” is folklore, and folklore does not tell you what to build.

Three mechanics, not one

The one-hour ceiling — the point at which a long agent session visibly deteriorates — is not a single phenomenon. It is three, and separating them matters because they have different fixes and only one of them is about size.

The consequence people find counter-intuitive is that a smaller, cleaner context outperforms a bloated one. Capacity was never the binding constraint; meaning per token was. Fill a two-hundred-thousand-token window with a hundred and eighty thousand tokens of irrelevant history and you have not given the model more to work with. You have given it more to sort through.

Which is Simon’s parable from the other end. Tempus’s problem was never that his workbench was too small.

Compaction is the sharp one

Of the three, compaction deserves its own paragraph, because it is the mechanic that most resembles the watch falling to pieces while you are still holding it.

Compaction does not merely end the context. It rewrites it mid-task. Some summarisation process reads the history, decides what matters, and replaces the original with a condensed version — and the agent that continues afterwards cannot tell what was removed. It has no gap to point at. It has a plausible, shorter past that it will reason from with complete confidence.

The handoff is total, not lossy

When a fresh agent picks up work from a dead session, the natural assumption is that something degraded — that it inherited a summary, or the gist, or the important parts.

It inherited what was written down. Nothing else. Not a compressed version of the reasoning; not the reasoning at all. Every intention, rejected branch, half-formed plan and “actually, let’s not do it that way” that lived only inside the previous session is simply gone, and the successor has no way of knowing it ever existed.

So the rule falls out without argument: the only durable state is state outside the window. Not “a good idea to write things down”. Structurally, the only thing that exists tomorrow is the thing that has a location today.

The arrangement that answers this has a name in our own canon: bounded units of work executed with fresh context, and an external layer holding progress, decisions and open questions. Stateful kernel, stateless workers. The keystone piece on wiki architecture reuses exactly this framing for long investigations — a substantial investigation is not one tool call, it is a stateful project made of stateless operations. The orchestration mechanics belong to that line of work. What matters here is the shape: the durable thing is outside, and the workers are disposable by design.

Back to the parable

Each of the three mechanics is a form of interruption, and interruption is exactly what Simon’s arithmetic prices.

Which gives us the bridge the rest of this book stands on:

The monolith is the thing you are holding when the phone rings.

That sentence is why the answer is architectural rather than a prompting trick, and it is why the same answer works at every scale. A thousand-line file, a forty-page specification, a fifty-tool agent, an un-navigable knowledge base: each is a partly assembled watch. The interruption arrives on a schedule you do not control, and the only variable you own is how much falls apart when it does.

“Isn’t this transitional?”

The objection deserves an early answer, because it is the reason teams defer the work: longer sessions and better memory are coming, so why architect around a limitation that is about to lift?

And notice the direction of travel. Agents are being pointed at longer jobs, more tool calls, more sub-agents, more days. The number of interruptions per unit of work is going up. Windows growing while jobs grow faster is not a problem receding; it is a problem being outrun.

The industry keeps treating agent mortality as a defect awaiting a patch. It is not a defect. It is the operating condition — and an operating condition is answered by architecture, not by waiting.

So decomposition survives interruption. Fine. But what exactly does a component buy you? Most people can name one benefit. There are at least four, and only one of them has anything to do with the size of the window.

Anyone who was building with coding agents in the early days remembers the same failure.

“Ever since I started coding with Claude Code and agent-based tools, the smaller the artefact, the better it did — especially early models. As soon as you got to a thousand lines it would start messing it up: not finding the right spot, deleting big chunks with patches accidentally. Smaller files did a lot better.”

Everyone who saw it explains it the same way. The file was too big for the context.

That explanation is true, it is comfortable, and it is about a quarter of the reason. Worse, because it names the window as the cause, it comes with an expiry date attached: if the problem is capacity, then capacity will fix it, and decomposition is a workaround rather than an architecture.

So what actually broke when the file hit a thousand lines?

Not one thing. A component does at least four jobs at once, and each one prevents a different, specific failure.

Only the first row is about the window. The other three are about something else entirely, and the second one is worth slowing down for, because it has been misdiagnosed for years.

The early disasters were addressing failures

Replay what actually happened when an agent mangled a thousand-line file.

The agent was asked to change something it could only describe approximately — “the validation block in the middle of the request handler”. To edit it, the agent had to produce a patch anchored on text it believed was there. In a large file, several regions look similar enough to be plausible anchors. The patch was applied to the best match. The best match was slightly wrong. And “slightly wrong” in a patch does not mean a small error — it means a chunk of code disappears.

That is not a comprehension failure. The model understood the request perfectly well. It could not locate the thing.

Small files make the filename the address. Directory structure is an addressing scheme. A function name is an address. A chapter number is an address. This is why file-level operations — write this file, replace this function — remain more reliable than span-level ones even now, and why the failure got rarer without ever becoming structurally impossible.

Regeneration, and why the grain decides your economics

The third job is quieter and compounds harder. A component is the largest thing you can cheaply delete and rebuild from its specification — which means your decomposition sets your regeneration granularity, whether you chose it deliberately or not.

Our own kernel doctrine holds that the durable asset in AI-assisted production is the generation recipe rather than any particular output: past a handful of patches, extract the judgment upstream, delete the artefact and regenerate. That advice is only executable if there is something small enough to delete.

If the smallest thing you can regenerate is “the whole document”, you will patch instead. Every patch is judgment trapped in edit history rather than promoted into the spec, and the trapped judgment is the thing that makes the next regeneration frightening. Coarse grain does not merely make regeneration expensive; it makes it unattractive, which is worse, because the decision gets made by reluctance rather than by analysis.

Parallelism is cut, not configured

The fourth job is the one that shows up as an operational surprise. Monoliths serialise agents by construction: the shared write surface is the lock. Two agents editing the same file are two agents queueing, or two agents producing a conflict.

Components remove the lock. Not by coordination — by there being nothing to coordinate. Ten workers on ten components produce ten diffs that do not touch each other.

There is an honest limit here, developed properly in Chapter 11: fan-out scales with independence, not with ambition. If the work is entangled, more agents produce more conflicts faster. But independence is a property of the cut, which is exactly the point.

The claim this whole book turns on

Now run the counterfactual, because it settles the objection more cleanly than any argument.

Suppose the window were infinite and attention perfectly uniform — the strongest version of “bigger models fixed it”. Which of the four dividends disappears?

One. The addressing problem is unchanged, because addressing is a naming property. Regeneration granularity is unchanged, because it is a boundary property. Parallelism is unchanged, because it is a dependency property. None of the three has anything to do with how much the model can see.

Which is why the author of this pattern conceded the model improvement and refused the conclusion in the same breath:

“I tend to think they don’t suffer from those problems now — but a thousand lines in a glass vial is still probably not good design.”

This is the most expensive wrong idea in agent architecture, and its cost is subtle: it converts an architectural defect into a waiting game. Waiting is free to start and impossible to finish. Every quarter brings a release, every release delivers a real improvement to the one dividend that was already the least important, and the team concludes that the remaining problems are the model’s fault.

Four jobs was the original count. Since this argument was first published, the canon has added two more — and one of them gets better as models improve, which turns the “wait for the next release” posture completely inside out.

This chapter is an amendment, and it is worth being explicit about that. The first edition of this argument named four jobs. Two more have been added since, both by other books in this canon, and both change what a good cut is worth.

A book that quietly absorbs its successors is a book you cannot audit. So: here is what was added, who added it, and what it does to the cut.

Fifth job: the unit of reuse

When regeneration was expensive, the finished thing was the asset. You protected the codebase because rebuilding it cost months. When regeneration becomes cheap, that ordering inverts — and it inverts completely.

That ranking is the inverted reuse hierarchy, and it is not this book’s. Its own summary of the shift is sharper than any restatement: people no longer download the reference implementation; they show the idea to their agent and say build the version of this that fits my work.

Why that is a decomposition fact, not just an economics fact

Because it tells you which of your components travel and which are local opinion.

A complete application is a bundle of local opinions: folder names, auth choices, entity schemas for that company, UI chrome for that audience. Those opinions are exactly what a portable kernel omits on purpose. So the question “where do I cut?” acquires a new criterion: cut so that the invariant is separable from the opinion.

Get that cut right and you can ship the invariant — to another team, another client, another project, or to an agent that will expand it into something locally fitted. Get it wrong, and the invariant is fused into the opinion, so the only transferable unit is the whole system. Which is to say: nothing.

Sixth job: the unit of reach

The second addition is newer and stranger, and it is the one that reverses the usual argument about model progress.

Reach is how far an agent can travel through meaningful relationships before it loses the intent, pollutes its context, or settles prematurely. The keystone piece in this canon names the metric — usable graph radius — and the effect it produces as models improve: the Traversal Dividend.

The behavioural observation behind it is worth stating precisely. Additional reasoning budget used to buy more deliberation over a fixed packet of information. Against a decomposed, mapped corpus it buys more travelling. The budget goes into constructing the right room to think in, rather than staring harder at the room you were handed. Vendors now recommend higher reasoning levels precisely for workloads where more exploration and verification pay off.²

Here is the decomposition consequence, which is this book’s part of that argument. Every hop costs attention, so hop size sets how many hops fit. Coarse units mean fewer, more expensive hops and a shorter reach — the agent spends its budget loading three enormous things and stops. Fine, well-mapped units mean a longer walk inside the same budget.

The table, extended

Two rows added to Chapter 3’s four. Same columns, so they can be read together.

If models keep improving, why does this get more valuable?

Count them. Of six jobs, exactly one was ever window-bound. Four are indifferent to model quality — addressing, regeneration, parallelism and reuse are properties of boundaries, names and dependencies. And the sixth improves as models improve, because a better traveller can use more of a well-cut map.

Which inverts the posture most teams have adopted. “Wait for the next model” treats the release as the thing that will make the work unnecessary. It is the opposite: the next model is the argument for cutting now, because it is the thing that will be able to walk what you cut. A price collapse in cheap tokens is just a cheaper chatbot to anyone without a substrate to spend the volume on, and a compounding advantage to anyone with one.

One last piece of housekeeping, in the interest of the audit. These two jobs are inferences — other people’s arguments applied to this one. They are strong inferences and they are not measurements. The book is better for saying which is which.

Six jobs, one decision. Which raises the obvious question, and it occupies the whole of Part II: given that this much rides on the boundary — how do you actually choose one?

Five hundred lines? Three hundred? One idea per page — whatever an idea is? Every team that takes decomposition seriously eventually holds a meeting about numbers, and the meeting never resolves, because the number is not the thing being decided.

Notice that nothing in Simon’s parable is about size. Hora’s subassemblies are about ten parts, and ten is not a target. Ten parts is where a subassembly holds together on the bench. Below that you are gluing loose parts together and calling it progress; above it the thing falls apart when you put it down. Size is what you observe afterwards.

The grain rule

The precise version of this in our canon is semantic closure: the smallest deterministic bundle whose meaning closes, reconstructed from the medium’s own structure — tree, thread, chapter, event cluster, timestamp — rather than from a storage record or a fixed-size chunk.

The word carrying the load is deterministic. Closure is found in the material’s own joints. It is not negotiated per document by a model in a good mood. If two runs disagree about where the unit ends, you do not have a unit — you have an opinion that will be re-formed differently next time, which puts you back in Chapter 2’s territory.

What closure looks like in five media

Over-atomisation is a real failure, not a theoretical one

Under-cutting has a loud, familiar failure. Over-cutting is quieter and better disguised, because it looks like diligence.

“Pure atomisation destroys meaning. A heading without its body, a punchline without its setup, two mutually reinforcing boxes split into lonely orphans.”

Each of those fragments is individually valid. None of them is a component, because none of them closes. Answering any question now requires reassembling six pieces, which means the reassembly step has acquired judgment — and Chapter 8 will explain exactly what that costs.

Call it the confetti cut. It reappears in Chapter 15 as one of the four named ways a decomposition fails.

Grain is a one-way decision

One consequence deserves stating even though it takes a sentence: the grain you choose bounds the precision of the relationships your system can ever express.

Average two things together and you have destroyed the edge between them permanently — not hidden it, destroyed it, because there is no longer anything on either end to connect. Address them separately and you have created the possibility of an edge, whether or not anyone draws it yet.

That asymmetry is why grain deserves more thought than file size ever did. Splitting a file later is a refactor. Recovering a distinction you averaged away six months ago means going back to the source material, if you still have it.

Span, levels, and the size of the map

Simon’s watch is a thousand parts, as a hundred and eleven subassemblies of about ten, across three levels. The hierarchy is not decoration. It is what keeps the map at every level small enough to hold.

Which gives a practical rule that resolves most arguments about structure:

If your map no longer fits on one screen, you need another level — not a longer map.

A flat list of four hundred components is a monolith with extra steps. It has all the interface cost of a decomposition and none of the navigability, because finding anything requires reading everything. Directories exist for the same reason subassemblies do.

Two failure directions, priced differently

So how small is small enough?

A working procedure, in four steps rather than a schedule:

1. Find the medium’s own joints. Function, chapter, thread, page, folder, turn. The material almost always has a structure; use it before inventing one.
2. Test closure forwards. Can this be read alone, by someone competent, without its neighbours?
3. Test closure backwards. Does anything here only make sense with its neighbour? If so, they are one unit and you were about to make orphans.
4. Only then look at size. If the result is uncomfortable, look for a missing level before reaching for scissors.

Everybody arguing about chunk size is arguing about the wrong variable. Meaning closes where it closes; the job is to find that seam. Picking a number is what people do instead of reading the material, and it produces components that are uniform, tidy, and cut through the middle of ideas.

You have units. They are the right size and their meaning closes. They are also, right now, opaque — the only way to know what is inside one is to open it, and opening things is the cost we were trying to avoid. Which is the second move.

“It is almost always incorrect to begin the decomposition of a system into modules on the basis of a flowchart. We propose instead that one begins with a list of difficult design decisions or design decisions which are likely to change. Each module is then designed to hide such a decision from the others.”³

David Parnas is cited constantly for “information hiding” and then almost universally ignored on the only question he was actually answering. His paper is not an argument for having modules — everyone already agreed about that in 1972. It is an argument that the criteria you use to draw the boundaries decide whether modularity helps at all.

What an interface is for

Across the planes this book covers, the same object wears different clothes:

• a function signature — name, arguments, types, and nothing about the body
• a chapter card in an outline — number, title, what it owns, what it must not re-explain
• a one-line index entry — enough scent to decide, not enough to satisfy
• a wiki page’s claim list — what this page asserts, without the argument
• a project dossier headline — what this folder is for, in a sentence
• a sub-agent’s task brief — objective, output format, boundaries

Two properties, and both are required. Cheap, or the caller opens the body anyway and you have added a step. Honest, or the caller opens the wrong body — which is worse than having no interface at all, because now the system is confidently misdirecting.

Parnas built the same system twice

The paper’s method is what makes it durable: he takes one system and decomposes it two ways.

The first cut follows the processing steps — the flowchart — because that is what all programmer training produces. Read the input, shift the lines, alphabetise, print. Four steps, four modules. It feels inevitable.

The second hides design decisions instead. The modules stop corresponding to steps at all: one owns line storage, another owns circular shifts, and whether alphabetisation happens as a phase or on demand becomes invisible to everyone else. Parnas notes drily that in this version the system could be built so that a user could not detect when the alphabetization was actually done.

Then he makes the observation that turns this chapter’s claim into a diagnosis:

“In the first modularization the interfaces between the modules are the fairly complex formats and table organizations described above. These represent design decisions which cannot be taken lightly… In the second modularization the interfaces are more abstract; they consist primarily in the function names and the numbers and types” of their arguments.³

He also dated his own advice, in a sentence that has aged unusually well: the flowchart “was a useful abstraction for systems with on the order of 5,000–10,000 instructions, but as we move beyond that it does not appear to be sufficient; something additional is needed.” The threshold moves; the argument doesn’t.

Why an agent makes this sharper than it was for humans

A person reading a badly cut module can hold the surrounding system in their head and cope. They grumble and get on with it.

An agent that opens a module and finds a design decision leaking out of the interface has to load the neighbours. That is the interruption cost from Chapter 1, charged again, on every single call — and it comes out of the same attention budget the actual work needs.

Bad interfaces do not merely cost comprehension. They cost context, which is the scarce good in this whole discipline.

The modern form: interfaces are generated

The most useful development since 1972 is that a good interface no longer has to be written by hand.

The repository-map pattern parses source with tree-sitter into an abstract syntax tree, builds a directed graph of definitions and references, ranks symbols by PageRank so the structurally important ones surface first, and renders signatures and structure, not full implementations, inside an adaptive token budget.⁴⁵

That is the interface card, produced on demand rather than curated by hand. And it generalises into a rule worth adopting: any component whose interface can be derived should have it derived, because a hand-written interface is a second artefact, and a second artefact can drift from the first.

Push the header; let the agent pull the ladder

There is a design consequence hiding in “cheap”, and it is the difference between an interface and a summary.

The read-side ladder in this canon runs from a one-screen map, through deliberately blurry pages, to a regenerated structural skeleton, to targeted search, to full source — and its governing rule is that resolution is chosen at read time, per question. Its diagnosis of the alternative is precise: a stuffed system prompt is knowledge frozen at a fixed resolution, chosen at write time, for every future question at once — simultaneously too much, because the agent pays attention on all of it every turn, and too little, because the one detail this task needs was below the cutoff.

That diagnosis applies at component scale, and it is this chapter’s contribution to it. An interface written to be complete has exactly the same disease as a stuffed prompt. It is a fixed-resolution guess about what every future caller will need. Write it to be cheap and sufficient for a routing decision, and let the caller descend when the decision demands it.

Which demotes a whole category of infrastructure in a useful way. The deterministic pre-processors — the skeletonisers, the parsers, the extractors — stop being pipeline stages that must run before anything happens, and become tools that materialise a resolution layer on request. The same function serves an ingestion pass and a query, and nobody has to pre-decide which artefacts deserved the expensive treatment.

How do I know the interface is cheap enough?

Run the test that Chapter 15 will formalise: could a competent caller decide to skip this component without opening it?

If not, the interface is decoration. And the flat version of the same test, for when you want to be unkind to your own work: if reading the interface costs what reading the body costs, you have made a filename, not a component.

Three ways interfaces fail

Most “modular” systems have components with no interfaces — just files with names. The interface is the part that does the work, and it is the part teams skip, because it produces nothing you can demonstrate in a stand-up.

Components with faces. Now they have to be findable — and a decomposition nobody can navigate is worse than the monolith it replaced.

Here is a real and common outcome. The monolith is gone. The units are well chosen and their meaning closes. Each one has a decent interface. And the system is worse than it was, because search cost went from bounded — read the file — to unbounded: which file?

A decomposition without a map is not a decomposition. It is a scattering.

What a map has to be

The same object, on every plane

The map is not a wiki thing or a code thing. It is a structural requirement that shows up wherever this pattern does.

That last row is worth a sentence, because it shows what a map buys beyond navigation. Cursor’s codebase indexing computes a Merkle tree of file hashes so that a small edit changes only the hashes of the edited file and its parents up to the root — which makes differential re-indexing nearly free. The map doubles as a staleness detector, and it can only do that because the components are addressable in the first place.

Why can’t the agent just search?

Two reasons, and the second is the structural one.

First, cost: search costs a call per guess, and a guess is only as good as the words you happened to choose. A map costs one read and tells you what exists.

Second, and more fundamentally: search finds text; a map gives relations. “What depends on this?” and “what else does this touch?” are not text-matching questions. They are questions about structure, and structure is either recorded or it is re-derived from scratch every time somebody asks.

Deterministic is not a nicety

A map that a model has to infer is not a map. It is a recomputation with a friendly name.

The whole value of the map is being the one part of the system nobody has to think about. The moment producing it requires judgment, it inherits every property you were trying to escape: it varies between runs, it consumes attention, and it can be wrong in ways that look entirely plausible. You have made the manifest into another component with a mortality problem.

Which produces the operating rule for this move:

Regenerate the map. Never hand-maintain it.

A hand-maintained index drifts from the day you stop tending it, and nobody tends it, because tending it is invisible work that never appears in anyone’s objectives. Make the map a build output of the components and the problem disposes of itself: a component that exists is in the map by construction, and a component that is deleted leaves no ghost behind.

The same reasoning applies one level up, and this canon has already worked it through for knowledge systems: if some tool genuinely wants a single flat file, generate that file from the graph rather than authoring it alongside — otherwise you have reintroduced the monolith and its drift under a new filename.

What a good map actually buys

• Navigation without loading. Decide where to go by reading names and relations, not bodies.
• Planning before spending. An agent can plan a walk before spending a token on content — which is what makes a long walk affordable at all, and connects straight back to the unit of reach.
• Staleness detection. If the map is derived, a diff over it tells you exactly what moved.
• Deletion safety. You can see what refers to a component before you remove it, which is the difference between refactoring and demolition.

Note that three of those four are properties the monolith had for free. It was always obvious where everything was, because there was only one place. What the map buys back is addressability at scale — the monolith’s single convenience, without its single point of collapse.

Maps have grain too

A map with an entry per component is right. A map with an entry per sentence is a second corpus, and now you have two things to maintain and no idea which one is authoritative.

If the map is approaching the size of the thing it maps, one of two things has happened: you over-cut (Chapter 5), or you are missing a level. Simon’s three-level watch is the reference shape, and the fix is almost always hierarchy rather than pruning.

A note on what happens after the map is walked

Units, faces, a manifest. One move left — and it is the one that gets skipped, which is precisely why so many careful decompositions quietly turn back into monoliths.

Seventeen chapter files, an outline, a list of includes, one redirect. That is the whole of it, and it is the most interesting thing about the build.

Everyone accepts the first three moves. Big things should be cut into small things — agreed since the sixties. Small things need faces — agreed since Parnas. You need an index — obviously. The fourth move is the one that gets treated as an implementation detail, and it is the one that decides whether any of the other three survive.

The rule

If composition requires judgment, you have re-imported the monolith at assembly time. That claim deserves unpacking, because it sounds like an aesthetic preference and isn’t.

• The assembler must hold everything. Which is exactly the interruption exposure you spent four chapters eliminating — now relocated, and now unavoidable, because assembly is the one step that genuinely does touch all the pieces.
• The assembly becomes non-deterministic. The same components can produce different wholes. Nothing in your version control tells you why.
• Defects appear at the seam, where no component owns them. You cannot write a test for a join that is allowed to use its discretion.
• You pay it on every build. Forever. Rather than once, at authoring time, when a human was there.

The monolith did not go away. It moved somewhere harder to see, harder to test, and more expensive to run.

The smart-assembly trap

It deserves a name because it is the most common way a well-executed decomposition fails, and because it is almost always introduced with good intentions — usually as “just a thin orchestration layer”.

What “understood cold” is actually measuring

Here is how the ebook build was described by the person who set it up:

“I built the ebook as PHP, so each rendered chapter was its own PHP file and we just included them in index.php. The writer could focus one chapter’s context at a time, and PHP runs fine without a server — php index.php > index.html and you’re done. It was a mechanism the AI coding tools understood cold.”

That last phrase is doing more work than it looks. “Understood cold” is not nostalgia for old technology. It is a measurement, and what it measures is that the join has no state in it.

Every model, every tool and every human already knows what include does.⁶ There is nothing to learn, nothing to explain in a prompt, nothing that can be misunderstood, and nothing that changes between one build and the next. A join that needs no explanation is a join that carries no hidden behaviour — and that, rather than any preference for the unglamorous, is the specification a recompositor should be held to.

The pattern, complete

But some joins really are hard

The rule looks naive until it survives a genuinely difficult case, so here is one. Fusing the results of a dozen parallel investigations into a single answer is not include. Findings overlap. Two probes contradict each other. One surfaced something none of the others saw. That is real work, and it needs judgment.

Does the rule break? No — the judgment moves to the ends.

The division of labour worked out for exactly this problem in our canon runs: a model frames the probes; deterministic code owns the union, the provenance, the route counts and the thresholds; then a model reads the fused object and decides once.

Look at what that preserves. The fusion is inspectable and repeatable — the same probes always produce the same merged object, so you can argue about the merge without re-running anything. The model’s judgment is applied to a thing that exists, at a moment you can point at, rather than being smeared invisibly across the joining. And the expensive pass happens once instead of continuously.

The general form travels well beyond assembly, and it is worth carrying out of this chapter: judgment at the ends of a pipeline is auditable — you can see what it was given and what it produced. Judgment in the middle is invisible, unrepeatable, and charged on every run.

What it costs you

Honesty first: a dumb recompositor is less flexible. It cannot fix a broken component, smooth over a mismatch between two of them, or paper across an inconsistency in tone or interface. Sometimes you will want it to, and that wanting will feel like a good reason to add a little intelligence.

Treat the wanting as a signal instead. A component that needs the assembler to rescue it is a component with the wrong boundary. The correct repair is upstream — re-cut it, or regenerate it from a better spec, both of which are cheap because of the unit of regeneration from Chapter 3. Chapter 15 formalises this as one of the four ways a cut goes wrong, because that is what it is: not an assembly preference, a boundary defect.

Every unit of cleverness in the recompositor is a unit of the monolith you failed to delete.

Which yields a diagnostic you can run this afternoon. If your build step needs a model, you did not decompose the work. You redistributed it and kept a copy.

That is the mechanism, complete. Four moves. What makes it a pattern rather than a practice is that the same four run on materials with nothing physically in common — which is the whole of Part III, starting with the plane everyone thinks they already understand.

Open any agentic codebase and you will find one: a triple-quoted string in the middle of a Python function. Four hundred words of instruction, indented under a def, describing how the model should behave, what it must never do, and what good output looks like.

It is a component with no address, no interface, and no owner. And it is sitting inside a plane that has been decomposed successfully for sixty years, which is what makes it interesting.

The plane nobody argues about

Functions and classes need no defence here. Sixty years of practice already agrees, and the four jobs from Chapter 3 map onto them so cleanly that the vocabulary was borrowed from this plane in the first place. Two sentences and move on.

What is different is not the code. It is what has arrived beside the code.

Prompts are components too

“I’ve been trying to pull prompts out of agentic code as markdown files forever, so they’re separately maintainable.”

“Separately maintainable” sounds like a preference. Score it against the jobs and it is four failures in one string:

And a fifth, quieter one: a prompt in a file can be diffed. A wording change becomes a reviewable line in a pull request rather than a silent behavioural change buried in a refactor.

The interface for this plane is generated

An agent working on a well-decomposed codebase does not read the codebase. It reads the interface layer — signatures, structure, docstrings, imports — and descends into bodies only where the work demands it. Chapter 6’s mechanism, applied.

The critical property is that this layer can be derived. It is not a second document that somebody promises to keep current; it is a projection of the first one, regenerated on demand.

Which layer am I actually cutting?

Here is the genuinely new development on this plane, and it is a boundary that moved underneath everyone.

The human-owned source is increasingly not the code. It is the retained package above the code: intent, design, prompts, worldview context, tests, starting state, and the decisions a regeneration must not re-guess. Generated code is compiled output relative to the agent, while remaining source input to the conventional toolchain — and it earns disposable-intermediate status only when a frozen package can regenerate equivalent tested behaviour.

The consequence is sharper than it first sounds. Every regeneration destroys everything held only in the output — and the whole promise of the regeneration economy is that outputs are cheap to throw away. So a decomposition that treats generated code as the primary artefact is optimising the disposable layer while the durable one stays undifferentiated: one folder, no boundaries, no interfaces, nobody’s job.

What belongs in the source package

• Intent, in the author’s own words, and dated
• Design decisions — including the alternatives considered and dropped, which is the part nothing else records
• Prompts and agent instructions, as files, per Chapter 5’s grain rule
• Tests and acceptance criteria — the behavioural contract the regeneration has to satisfy
• Fixtures and starting state, so the regeneration begins from the same world
• Constraints that must not be re-guessed — the rules whose rediscovery cost you a week the first time

Notice that almost all of it is text. Which is convenient, because text decomposes into files as naturally as code does, and gets the same four dividends from doing so.

One neighbour worth naming and leaving alone: coding-session exhaust is a distinct asset class with the same shape — intent in your own words and dated, alternatives rejected, things planned and never built, all structurally invisible in the finished repository. Same producer, different artefact, its own book.

What this plane teaches the other four

Code is where this pattern has been practised longest, with the best tooling and the most experienced practitioners — and the source layer was still drawn in the wrong place for two years while everyone got on with splitting files.

That is the transferable lesson, and it is why this chapter opens Part III rather than closing it:

The hardest decomposition question is not how to cut the thing in front of you. It is whether the thing in front of you is the thing that should be cut.

Every plane in Part III has a version of that mistake, and Chapter 15 turns it into one of the four axes of cut. If you find yourself carefully subdividing something and getting no dividends, the problem is rarely granularity. It is usually that you are cutting the output of a process whose inputs were never separated.

That is the plane with the most history and the least novelty. The next one has the least history, and you are currently inside it.

Every pattern book eventually reaches for a case study, and the case study is usually somebody else’s system, described from the outside, with the inconvenient parts smoothed over.

This one is different in a useful way: the specimen is this book. You can inspect it, and the assembly step is a shell command.

The four moves, against the actual build

Why it works from both ends

For the writer: one chapter’s context at a time, plus the map for continuity. The writer never holds the book. It holds one argument and a description of its neighbours — which is Hora’s bench exactly. Put it down, pick up the next one, lose nothing.

For the reader: nothing changes. The output is a single document with working anchors and a table of contents. The decomposition is invisible at the point of consumption, which is precisely where it should be invisible.

What each job actually bought

The parallelism row is the honest one, and it is worth dwelling on rather than glossing. The capacity existed. Seventeen chapters could have been written by seventeen workers at once, and the components are independent enough that they would not have collided.

They were written serially anyway, because the dependency graph — not agent capacity — sets the fan-out. Chapter 8 refers back to Chapter 3’s table by name. Chapter 13 corrects a claim Chapter 12 makes. A parallel write produces seventeen chapters that each assume the others said something slightly different, and the repair costs more than the sequencing saved.

What travels, and what doesn’t

Apply the inverted reuse hierarchy from Chapter 4 to a publishing pipeline and it sorts the assets immediately:

1. Most valuable: the North Star and the domain distinctions — what this book owns, what it refuses, where its fences are.
2. Then: the structural conventions — the chapter card format, the part shape, the citation contract, the component inventory.
3. Least valuable: the finished chapters. Most locally opinionated, easiest to regenerate, and the thing everyone instinctively protects.

The practical consequence for anyone running a content pipeline: invest in the outline and the conventions; treat the prose as expendable. Hand-nursing a paragraph is a tell that the plan was underspecified, and the correct repair is to improve the plan and regenerate — which the decomposition made affordable in the first place.

Why not just generate the whole thing and edit it?

It is the obvious alternative, and it fails on every one of the six counts — worst on regeneration.

Improving chapter 3’s argument in a monolithic build means regenerating a document containing sixteen other chapters you were happy with. So you patch instead. And patching is how judgment gets trapped in edit history rather than promoted into the spec, which is the trap Chapter 3 described at file scale, now operating at document scale.

The tell is familiar to anyone who has done it: after four rounds of edits, nobody dares regenerate, because nobody can remember which improvements exist only in the output.

Past books

The same shape covers any composed artefact, and the test does not change:

• a proposal with a section per module and a manifest that orders them
• a report assembled from independently produced analyses
• a slide deck built from panels that can each be regenerated alone
• a landing page composed of partials
• a specification assembled from requirement units with stable identifiers

In every case, ask two questions. Can you rebuild one part without regenerating the rest? And is the join mechanical? If both answers are yes, you have the pattern. If either is no, you have a monolith with a folder structure.

Two planes down, and both of them produce something you can hold. The third produces behaviour — and it is where the cut turns out to have more than one axis.

Everyone has built it once. A single agent with fifty tools and a thousand-line prompt, expected to handle support enquiries, update the CRM, generate the report, send the email and escalate when it gets stuck. It is slow, it is expensive, and it cannot be changed without breaking something unrelated.

It is also, structurally, a monolith wearing a costume.

The monolithic agent trap

The failure modes are catalogued in our own canon and do not need re-deriving here: prompt bloat, context overflow, brittle logic, and a maintenance problem where changing how emails are sent means finding the right ten lines in a thousand-line prompt without breaking the other nine hundred and ninety. The answer is a thin router, an orchestrating supervisor, and single-responsibility workers, each holding one job and only the tools it needs.

That is the agent plane’s version of Chapter 5, and it is well covered. What is more useful here is the part that transfers.

The cheap interface, for agents, is the brief

A worker’s interface is not its code and not its tools. It is its brief: an objective, an output format, guidance on which tools and sources to use, and clear task boundaries. Anthropic’s own guidance on multi-agent systems states both the requirement and the failure — without detailed task descriptions, agents duplicate work, leave gaps, or fail to find necessary information.⁷

Duplicated work and gaps are exactly what a bad interface produces on every other plane too. The difference is that here you can watch it happen in an afternoon, which makes this the cheapest plane on which to learn what a good interface feels like.

The second axis

Here is where this plane teaches something the others cannot.

The scout–senior split cuts one task along a time seam — a gathering phase and a judging phase — and passes the entire exploration transcript across that seam intact rather than summarising it. A cheap, cached, read-only model explores thoroughly and decides nothing; then the brain is swapped over the frozen transcript and a frontier model inherits everything, including the dead ends, and emits one decision.

The conversation is the working set.

Why the axis matters more than the granularity

State it flatly, because it redirects the whole repair when a decomposition is failing:

Split a research task by topic when the real seam is gather-then-judge, and you get five workers who each summarise away the thing the decider needed — the near-misses, the branch that looked promising and wasn’t, the source that was checked and found irrelevant. Every worker did its job correctly. The assembly is still worse than one competent agent working alone.

And nothing about making those workers smaller helps. That is the diagnostic value of the observation: when a decomposition feels wrong but every component looks reasonable, stop resizing and change the axis.

Parallelism is cut, not configured

Fan-out is a property of the decomposition. The orchestrator only schedules what the cut made possible.

Two mechanisms are routinely confused, and distinguishing them is most of the craft:

The scale available is not theoretical. Dynamic-workflow tooling now orchestrates tens to hundreds of parallel sub-agents in a single session, with one documented case porting roughly 750,000 lines from Zig to Rust at a 99.8% test pass rate in eleven days.⁸

And then the limit, from a practitioner watching the same machinery on a real backlog:

“More than three concurrent tracks doesn’t help — the dependency graph, not agent capacity, is the constraint.”

Fan-out scales with independence, not with ambition. Which is a decomposition statement wearing an orchestration hat: independence is something you cut for, not something you configure afterwards.

Dumb recompose, on this plane

How do worker outputs join? If a supervisor reads everything and works out what it all means, you have a smart seam — Chapter 8’s trap, with a job title.

The disciplined version: each worker returns a structured result, the merge is deterministic, and where genuine judgment is required it is applied once, at the end, over the fused object. There is a cost lesson underneath this too. Many small mutation calls each re-process the entire accumulated conversation, so N incremental writes cost roughly N passes over a growing context; one terminal structured document costs approximately one pass. The cheap architecture and the governable one turn out to be the same architecture.

One consequence of doing all this properly is worth noting, because it is what a well-cut agent plane feels like from the outside: once the knowledge lives in a shared substrate rather than inside each agent, every agent you write is nearly the same agent — same toolbelt, different North Star, different inputs. Agent number seven costs a paragraph.

That volume is affordable because cheap, cached tokens made exploration nearly free — and a price collapse only compounds for whoever has an architecture that can spend the volume.

Code, artifacts, agents. The fourth plane is the one where the software vocabulary stops being borrowed and starts being literal.

You describe a knowledge graph to an engineer and reach for software words because they are convenient. Pages are “sort of like” functions. Edges are “kind of” a call graph. The index is “basically” a manifest. It is a serviceable metaphor and it buys you a shorter conversation.

Then you sit down to write the maintenance agent, and you notice that you are not using the words loosely. Every operation you need already has a name, and the name is a refactoring.

The correspondence, sharpened

The base mapping is straightforward after four chapters of the same shape: pages are functions, typed edges are the call graph, the index is the manifest, claims are statements.

Since the first edition of this argument, that mapping has been made considerably more precise elsewhere in this canon, and the sharper version is worth reproducing whole:

Three of those rows deserve comment rather than being left to speak for themselves.

Function ↔ claim. The unit is the claim, not the paragraph. A claim should survive paraphrase — that is what makes it addressable and re-referable. A quotation should not survive paraphrase, because its job is exact language. Confuse the two types and the graph gets fat and brittle simultaneously: fat with prose, brittle because nothing can be safely restated.

Interface ↔ identity plus provenance. On this plane the cheap interface is what the claim is and where it came from. Without provenance you cannot falsify it. Without a stable identity you cannot refer to it twice. That is Chapter 6’s definition, translated into a medium where the “body” is an argument rather than a function.

Debug symbols ↔ prompts and transcripts. More on that below; it turns out to be a decomposition argument rather than a hoarding one.

Roles, not just topics

A function is not merely “about payments”. It validates a card, charges a customer, or emits a receipt. Likewise a claim is not merely “about prompting”. It is a premise, a mechanism, a consequence, an exception, or a proof.

Role is part of the interface. It is the difference between knowing that two components are connected and knowing what the connection does — which is exactly the difference between a call graph and a pile of names.

The janitor is a refactoring engine

Here is the moment the correspondence stops being interesting and starts being useful. Line up what a knowledge-graph maintenance pass does against what a refactoring tool does:

The mechanics of that pass — chronological stacking, the lint sweep, contradiction-as-edge, keeping raw figures out of the graph entirely — belong to the book that developed them. What matters here is the correspondence, and what the correspondence bought.

You didn’t build a knowledge base that resembles a codebase. You built a codebase whose language is claims — and imported forty years of software maintenance discipline for free.

That is the argument of this chapter, and it explains something otherwise mysterious about why these systems work at all. Nobody had to invent knowledge-base maintenance. Refactoring is a solved craft — forty years of practice, vocabulary, failure modes, review discipline and tooling instincts — and all of it transferred the moment the mapping was tight enough to import operations rather than merely suggest them.

Note also which direction the borrowing runs. This is not a knowledge system reaching for engineering credibility. It is an engineering discipline discovering it had already solved somebody else’s problem, in a different vocabulary, decades earlier.

Why did the maintenance system arrive pre-invented?

Because the cut was drawn in a place where the correspondence held exactly. That is the general lesson, and it generalises past wikis:

So when you find yourself reaching for software words to describe something that is not software, check how tight the mapping is. If it is loose, you have a helpful image. If it is tight enough to import operations — deduplicate, extract, split, test — then stop designing and go and read the prior art, because somebody spent forty years on your problem while calling it something else.

Debug symbols, and why that row is about cutting

Binaries ship stripped. Names, comments and intent vanish at compile time, which is why teams reverse-engineering legacy systems spend most of their effort reconstructing purpose from behaviour and residual structure. That work is heroic, and it is heroic entirely because an intent stream was discarded years earlier.

Keep the raw layer — prompts, transcripts, intent notes, acceptance tests — and reconstruction becomes source-mapped rather than speculative. The public formulation of the same instinct in the wild is the raw-sources layer of the LLM Wiki pattern: immutable documents the system reads and never modifies.⁹

Applied to this book’s argument: an interface that carries provenance is the difference between a component you can trust and one you have to re-derive. Strip provenance from a claim and you have manufactured a component that works right up until somebody asks why — at which point it is a mystery delivered in a confident tone.

That is also why similarity search alone cannot substitute for typed edges here. Vector retrieval is a reasonable sensor for “this might be nearby”, and it is weak precisely on how facts connect across hops.¹⁰ Connection is structure, and structure is either recorded or re-derived on every question.

What this plane teaches the others

Two things, and the second one is quietly the most useful observation in Part III.

First, correspondence beats analogy, as above.

Second: the interface is where each plane’s difficulty concentrates. On code it was signatures and the question of which layer was really the source. On artifacts it was the chapter card. On agents it was the brief. Here it is identity and provenance. Different materials, same bottleneck — which suggests that when a decomposition is not paying, the interface is the first place to look, before the boundaries and long before the tooling.

One neighbour, named and left alone: the puzzle of why a “kernel” document kept needing multiple versions resolves on this plane too — multiple kernels were never a design, they were a workaround for a monolith that could not be queried. That argument has its own book and this one will not re-make it.

The first edition of this book stopped here, with a tidy closing line about the wiki being the fourth plane and probably the last. That line did not survive contact with the following year.

Being wrong in a pleasant direction is the best kind of wrong, and it is worth doing in public rather than quietly deleting the sentence.

Three ranked lists are not an investigation

Picture the institutional question that never fits a FAQ. Somebody needs to know what is going on — not a clause lookup, but a multi-hop sense-making problem across projects, people, prior decisions and soft evidence that never reached a dashboard.

They open an agent, and the agent does what agents are built to do. It searches. One careful query, ten ranked hits, a fluent summary. Something feels thin, so there is a second search. Then a third.

By the end of the conversation the human has three answer-shaped packages and is still holding the actual job: remembering why they asked, comparing the overlaps by eye, noticing the finding that only one framing surfaced, and deciding where a careful read is still required.

That failure mode is so common it has become invisible. It gets called “using retrieval”. It is serial answer generation with the fusion step unpaid and unowned.

Three words that everyday speech collapses

The individual questions are retrieval probes. They are not the actual job.

Where the monolith is hiding

When a system treats the last sentence typed as the unit of work, the parent purpose lives nowhere except inside the conversation — which is, by Chapter 2’s account, the single most mortal container in the entire stack.

That is Chapter 1’s failure exactly, in a place nobody thought to look for it. Tempus, holding a thousand parts, in the one workshop where the phone rings every turn.

The four moves, applied to a question

• Decompose — the parent intent into probes, chosen for coverage rather than phrasing. A boundary question, a contrarian framing, a stakeholder lens: none of them need to be what the user typed, and all of them need to close the purpose.
• Interface — each probe carries its provenance and its coverage role: what it was sent to find, and why. Without that, results arrive as an undifferentiated pile, and overlap gets noticed late or never.
• Map — the fused evidence graph, with route counts and convergence recorded, so you can see which findings independent probes agreed on and which came from exactly one framing.
• Dumb recompose — the union, the provenance and the thresholds are deterministic. A model does not collage tool dumps into an answer; it reads a compiled object and judges once.

Which is Chapter 8’s rule surviving its hardest case — the two chapters are the same argument, seen from opposite ends. Judgment frames the probes, machinery fuses the results, judgment reads the fusion.

Four costs of leaving the job whole

The machinery that addresses those — the question portfolio, multi-query graph fusion, selective resolution where independent routes meet, the inspectable resolution package — belongs to The Intent Compiler. This chapter takes the shape and leaves the engine where it lives.

What the five planes have in common

Now that the set is complete, the pattern behind the pattern is visible. On every surface, decomposition became necessary at the moment somebody noticed that the thing being held whole was too big to survive an interruption:

Which yields a diagnostic more portable than any of the five instances:

What am I holding whole — and what happens to it when the phone rings?

So what’s the sixth plane?

Unknown. And this book is not going to guess, because it already made that mistake once, in print, at the end of Part III.

The honest position: there will be another surface, it will look obvious in hindsight, and the way to find it is the diagnostic above rather than a prediction. Somewhere in your stack there is something being held whole because nobody has yet noticed it is a thing — the way nobody noticed the question was an artefact until three ranked lists stopped being an answer.

A doctrine that cannot revise its own closing claim in public is a brand, not a doctrine.

Five planes, four moves. On every one of them, the moves were the easy part — and choosing where to cut was the work. Which is the whole of Part IV.

Simon’s systems are not decomposable. They are nearly decomposable, and the qualifier is not a hedge. It is a specification, with two propositions attached:

“(a) in a nearly decomposable system, the short-run behavior of each of the component subsystems is approximately independent of the short-run behavior of the other components; (b) in the long run, the behavior of any one of the components depends in only an aggregate way on the behavior of the other components.”¹

Approximately. In only an aggregate way. Not not at all. The interactions across boundaries are weak, not absent — and a design that assumes they are absent will be wrong in a way that only surfaces under load.

Simon’s worked example is a building. Rooms inside insulated outer walls; cubicles inside rooms; poor partitions between cubicles and good ones between rooms. Heat crosses everything. It simply crosses some boundaries far more slowly than others.

Which is what a good cut actually looks like. Not a wall. A rate difference.

Cross-cutting concerns are why edges exist

Once you accept that boundaries leak by design, the concern that touches everything stops being an embarrassment. It has three possible homes, and only one of them survives contact with change.

Which gives a claim worth stating plainly, because it inverts how most people read a dependency diagram: an architecture with no cross-component relationships has not eliminated coupling. It has hidden it. The coupling is in the duplicated paragraph, the shared assumption, the convention everyone follows and nobody wrote down.

What do I do with the concern that touches everything?

Give it a home and let everything point at it. Contradictions, supersessions and genuine disagreements get the same treatment — kept as typed relationships rather than resolved away into a confident middle. Two departments in real disagreement is a fact about the organisation; a system that tidies it into a single answer has not simplified anything, it has lied.

The god-object smell

Here is the diagnostic that comes out of taking “nearly” seriously.

That last point is the one teams get wrong most expensively. A hub page, a utils module, a supervisor agent that has quietly acquired eleven jobs — the instinct is to move things out of it until it looks reasonable. What you end up with is a slightly smaller hub and a scattering of orphans, because the boundary that produced the hub is still there and still attracting.

The healthy shape has a name

Simon gives it one, in the most quotable passage in the paper:

“Most things are only weakly connected with most other things; for a tolerable description of reality only a tiny fraction of all possible interactions needs to be taken into account. By adopting a descriptive language that allows the absence of something to go unmentioned, a nearly empty world can be described quite concisely. Mother Hubbard did not have to check off the list of possible contents to say that her cupboard was bare.”¹

Sparse across, dense within. If your graph does not look like that, you have not found the joints — you have imposed some.

The second sentence is the underrated one, and it explains something about maps. A language in which absence can go unmentioned is a language in which the map stays small. That is why maps of well-cut systems are short and maps of badly cut ones are exhaustive: when everything might be connected to everything, the map has to say so, and saying so is most of the content.

Why this matters more than tidiness

Simon has one more argument, and it is the strongest reason this is a chapter rather than a caveat:

“If there are important systems in the world that are complex without being hierarchic, they may to a considerable extent escape our observation and our understanding.”¹

Read that as an operational claim rather than a philosophical one. A badly cut system is not merely inconvenient. It is partly invisible to the thing trying to work on it — human or agent. The pieces you cannot describe separately are the pieces nobody reasons about separately, and those are exactly where the surprises live.

It is also the honest answer to a question every team eventually asks: why does the agent keep missing that? Sometimes it is a retrieval problem. Sometimes the thing has no describable boundary, so there is nothing to retrieve — only a region.

Where the qualifier bites, in practice

So the target, restated as doctrine: the goal was never independence. It was strong inside, sparse across, with the crossings made explicit instead of hidden — because explicit crossings are navigable, and hidden ones are surprises on a delay.

Chasing perfect separability produces one of two artefacts, and both are familiar. A god object holding everything that refused to separate. Or a confetti graph in which every relationship was thrown away in the name of tidiness. Simon’s qualifier is the thing that keeps you out of both.

That is the shape to aim for. Which leaves the question the reader has been holding since Chapter 3, and it deserves an answer with tests attached rather than principles.

Everything so far has argued that the cut is the scarce judgment. That is a useful thing to believe and a useless thing to be told, so this chapter hands over the tests that make it a decision rather than a matter of taste.

Test 1 — the change test

This is the test people skip because it requires predicting change, which feels speculative. It is less speculative than it sounds: most teams can name their five with no hesitation at all, and the exercise takes twenty minutes. What makes it uncomfortable is that the answer usually indicts a structure somebody is proud of.

Test 2 — the interface-cheaper-than-body test

The virtue of this test is that it is observable rather than theoretical. You do not have to argue about whether an interface is good; you watch what a caller does with it.

Test 3 — the family test

This is the newest of the three and the one that catches a failure the other two miss: a boundary that is internally coherent and describes nothing generalisable. Components like that work fine, right up until you try to reuse them, hand them to somebody else, or explain them to a new agent.

Four axes of cut

Part III surfaced these one plane at a time. Together they are the more useful object, because a decomposition is chosen along an axis long before anyone argues about size.

Most failed decompositions cut on the wrong axis, not at the wrong granularity.

Which produces the most useful diagnostic in this chapter: when a decomposition feels wrong but every component looks reasonable, stop resizing and change the axis. Resizing a topic-cut system that needed a time cut just gives you more, smaller workers that each summarise away the same thing.

Four ways a cut goes wrong

The fourth one is worth restating in this company, because Chapter 8 introduced it as an assembly preference and it is not. A smart seam is a cut failure. The components were cut such that they cannot be joined mechanically — usually because closure was drawn slightly wrong, so each piece leaves an edge that something has to reconcile. The intelligent assembler is not the disease. It is the symptom you hired.

Repairing a bad cut

One line, borrowed from our resolution doctrine and applicable here without modification: escalate to the layer where the defect lives. A bad cut is not patched at the component. It is re-cut, and the components are regenerated from their specs.

That is only affordable because of the unit of regeneration from Chapter 3 — which is a pleasing property worth noticing: the pattern makes its own mistakes cheap to fix. A decomposition you can regenerate is a decomposition you can afford to get wrong once.

It looks fine and it feels wrong. Now what?

Not every imperfect boundary is worth moving. Move it when a likely change keeps crossing it; when the interface has grown to the size of the body; when a component has become a hub; or when the assembler has started needing judgment. Leave it when the only complaint is aesthetic — symmetry is not one of the six jobs.

The tests running together

A short worked pass, because three tests in isolation are easier to admire than to use.

Take a support agent that classifies incoming messages, looks up account context, drafts a reply and escalates when it is out of its depth. The topic axis proposes the obvious four workers: classifier, lookup, drafter, escalator.

Now run the change test. What actually varies? The escalation policy changes weekly — it is a business rule with an owner and an argument attached. The draft tone changes monthly. The classifier changes rarely, and the lookup almost never. So three of the four “components” are stable and one of them is a moving policy fused into a worker that also holds prompt text and tool access.

The interface test then asks whether a router could decide from briefs alone — and the answer is no, because “escalate” means something different every week and the brief cannot keep up.

The resulting cut is not the obvious four. It is three workers plus an escalation policy as its own component with its own owner, its own review, and an interface the workers read. That boundary does not appear anywhere on the process diagram, which is exactly Parnas’s point.

Tests, axes, failure modes. What is still missing is the unflattering part: what this costs, and the cases where doing all of it carefully still leaves you worse off than a single well-organised file.

A doctrine that only describes the happy path is marketing with footnotes. So: the boundary, the bill, and the things this book is not claiming.

When should I not do this?

Every one of the durable dividends is a dividend on revisiting. Addressing pays when something is edited. Regeneration granularity pays when something is rebuilt. Parallelism pays when several things happen at once. Reach pays when something is traversed. Reuse pays when something is inherited.

If a piece of work is produced once and never touched again, none of them pay, and you have bought interface cost and map cost for nothing.

The bill, itemised

The third row is the one people underestimate by the largest margin. Boundary stewardship never finishes, because the system keeps changing and the right cut keeps moving. It is not a project with a completion date; it is a standing judgment, the same class of work as keeping a codebase’s module structure honest.

Which is the honest framing of the whole trade: the burden moved; it did not vanish. The trade is good because the new work is stewardship of an asset that compounds, while the avoided work — recalibrating a monolith on every change and every model release — is work that evaporates. Same hours, opposite direction.

What this book is not claiming

Shape is enough to act on. A penalty that grows superlinearly in the size of what you are holding, under an interruption rate you do not control, is an argument you can make decisions from without knowing the constant.

The experiment that would settle it

Nobody has run it, including us. That is a real gap, and it is a better position than a number nobody can reproduce.

One counter-case, taken seriously

A well-written monolith with an excellent table of contents genuinely beats a badly cut decomposition with no map.

That is not a rhetorical concession offered to seem reasonable. It happens constantly, and anyone who has inherited a “modular” repository of two hundred one-function files knows exactly how much worse it is than the four-thousand-line module it replaced.

But notice what the concession actually shows. The monolith with a good table of contents has an interface, a map, and one very large component. It has three of the four moves. That is why it competes — and it is also why it hits a ceiling the moment anything needs to be regenerated in part, edited concurrently, or traversed by something that cannot hold the whole file.

Over-application is the other failure

The failure mode of a persuasive pattern is that it gets applied everywhere, by people who have just read about it, to things that never needed it. That is partly what Chapter 15’s tests are for: if a proposed cut fails the change test, the interface test and the family test, you are not being disciplined. You are making filing cabinets.

A pattern that claims a number it does not have will be believed once and distrusted forever. The mechanism is the claim, the mechanism is checkable, and that is a considerably better position to argue from.

That is the honest accounting. What remains is the part you can start on Monday.

The smallest useful move is not “split the biggest file”. It is: find the thing you are holding when the phone rings.

Step 1 — Find the monolith by symptom, not by size

Whatever answers two or more of those is your monolith. It may not be the largest thing you own, and it frequently isn’t — the worst offender is usually a mid-sized artefact that everything depends on and nobody owns.

Step 2 — Cut on change, not on flow

List the design decisions most likely to change in the next year. Draw boundaries that hide them.

Fair warning, because it will feel like a mistake at the time: the resulting boundaries will look wrong relative to the processing order. Your modules will not correspond to the steps on the whiteboard. Parnas said so in 1972, and it still feels wrong the first time you do it.³ The discomfort is the signal you did it right.

Step 3 — Give each piece a cheap interface

Signature, chapter card, one-line index entry, claim list, task brief. Then run the test: can a caller decide not to open the body? If not, the interface is decoration.

Derive it wherever it can be derived. A hand-written interface is a second artefact, and a second artefact will drift from the first — usually just after the person who wrote it moves on.

Step 4 — Generate the map

Never hand-maintain it. A component that exists should be in the map by construction; a component that is deleted should leave no ghost. If the map doesn’t fit on a screen, add a level rather than a scrollbar.

Step 5 — Delete the intelligent assembler

This is the step that will feel like a downgrade and isn’t.

If assembly currently requires a model, that model is holding the monolith on your behalf — on every build, forever. Replace it with a function call, an include, or a script. Where the join genuinely needs judgment, move the judgment to the ends: frame, compile deterministically, decide once.

Three things not to build

• A bespoke assembler. It will be introduced as “just a small orchestration layer” and it will end up holding the whole system.
• A hand-maintained index. Somebody will promise to keep it current. Nobody is lying; it simply will not happen, because the work is invisible.
• A granularity chosen by line count. “Nothing over three hundred lines” produces components that are uniform, tidy, and cut through the middle of ideas.

Sequencing an existing system

Most readers are not starting fresh, so one piece of advice matters more than the rest: cut one monolith completely — including its map and its dumb join — before touching the second.

A half-decomposed system has all the interface cost of the pattern and none of its dividends. It is also the state in which most “modularisation initiatives” die, because six weeks in there is nothing to show, the costs are all visible and none of the benefits are, and somebody sensible asks what this is for.

What hasn’t changed

Sixty-four years after Simon and fifty-four after Parnas, the interesting part of this is the same as it always was. Anyone can split a file. The judgment is in the cut — which decisions to hide, where meaning closes, what the interface has to carry, and how to keep the join stupid enough to trust.

What has changed is the penalty

In 1962 a bad decomposition cost you rework. It was expensive, and it was recoverable, and mostly it was somebody’s problem next quarter.

In 2026 a bad decomposition costs you an agent population that cannot address, cannot regenerate, cannot parallelise and cannot travel. A workshop full of Tempuses, all of them starting over every time the phone rings — and the phone rings every hour, because you built a workshop where interruption is the operating condition rather than the exception.

The hard part was never writing the modules. It was choosing where to cut.

Decomposition is how work outlives the worker — and your workers die every hour.