The Rooms You Don't Read

There is a ceiling in your skull and it has not moved since long before any of this. Call it seven or eight — the number of separate things a person can hold live at once, the working set behind your eyes. For most of software history the code was the bottleneck and that ceiling had slack to spare. Then the loops from part five started working. The AI began shipping faster than you could read, and the bottleneck slid off the machine and onto the one component in the system that cannot be scaled: you. The failure this time isn’t that the AI is too slow. It’s that you filled up — and a full head is a slow, error-prone, knackering place to run a codebase from. That last word is Matt’s, and it’s the most honest one in the talk.

The move that fixes it is one I’d have called negligence a year ago. There’s a module in tinkforge — the one that splits a PDF — whose outside I designed with care and whose inside I then, deliberately, stopped reading. I couldn’t walk you through it line by line anymore. I know its door, I know its tests pass, and I have chosen not to look. That isn’t laziness dressed up as method. It’s the last fundamental in this series, the human payoff of every structural one before it, and it reads as a vice right up until you see what it buys: the room comes off your head. You hold the door — six lines — and you let the room go.

Here is the door, the whole of it:

export async function runSplit(
  inputBytes: Uint8Array,
  segments: readonly Segment[],
  rotations: PageRotations = {},
  options: RunSplitOptions = {},
): Promise<Blob[]>

Bytes in, a plan for where to cut, two optional dials, blobs out. That is the entire contract for splitting a PDF — the sum of what a caller has to carry in their head to use it. Behind that signature sits three hundred and ninety-three lines of splitting logic, and behind that sits the part I want you to feel: the actual surgery is done by qpdf, a mature C++ PDF library, compiled to WebAssembly and shipped inside the page as a 2.18-megabyte binary — 2,183,781 bytes of machine code I did not write, do not read, and could not review in a year of Sundays. Six lines out front. Two-and-a-fifth megabytes of stranger’s C++ behind. That ratio is the whole idea: the depth of a module is the work it does divided by the size of its door, and this door is about as small as a door gets while the room behind it is about as big.

So how do I dare? Not by trusting the room. You don’t earn the right to stop reading two megabytes of C++ by deciding it’s probably fine — that really is negligence. You earn it at the door, with a test that goes through it and refuses to trust anything else. The split module’s test synthesises a real PDF, asks the real qpdf to cut pages one through three out of it, and then reads the page count of what comes back — back through qpdf itself — and asserts it’s three. It never stubs the engine, never fakes a return value, never checks what the wrapper said it did. The file states the rule in a line I keep coming back to: “qpdf is never mocked — mocking it would test nothing.” The boundary is pinned against reality instead of against my belief about reality, and that is the whole difference between a gray box and a prayer. I’m not choosing not to look because I trust the code. I’m choosing not to look because the test looks for me, every run, at the only thing that matters — the answer at the door.

Here is the part that caught me out when I went looking. You would assume a door like that is a wall — that the language makes the room private, that something stops a careless import from reaching past the six lines and grabbing at the machinery inside. Nothing does. TypeScript has no internal; there is no barrel file sealing the internals, no package boundary, no lint rule forbidding the reach-through. Any file in the codebase could import straight into the guts of the split module tomorrow and the compiler would not say a word. The door isn’t enforced. It’s observed.

So what holds it? The same two things that have held every fundamental in this series: the tests and the names. The seam stays real because the test only ever speaks to the door, which makes the door the one surface that has to keep working — rearrange the room and the test doesn’t flinch; break the contract and it goes red. The privacy stays real because everyone who touches the code, me and the AI I hand the room to, agrees to treat runSplit as the entrance and the rest as behind-the-wall, and part three’s glossary is where that agreement is written down. You can even watch the discipline happen in the types: one level further in, the hand-written declarations over qpdf describe “only the slice of the Emscripten Module API the wrapper actually uses, rather than typing the whole runtime” — a hundred and forty lines deliberately cut to a keyhole, in front of a binary no one reads. The gray box was bought with discipline, not with an access modifier. That’s worth saying plainly, because it’s easy to assume you need the compiler’s permission to work this way. You don’t. You need a boundary you can test through, and the will to respect a wall that isn’t there.

Now scale that from one door to the whole app, because that is where it stops being a neat trick and starts being the thing that saved my brain. tinkforge is, from where I sit, seven or eight rooms: split, merge, compress, convert, watermark, build from images, encrypt — the operations a person actually reaches for. Count by code module instead and it’s ten. Either way it lands on the number the talk keeps circling back to, the seven or eight lumps of stuff a human can hold live at once. And that is the entire move. I don’t hold the app. I hold the doors — seven or eight of them, the interfaces and how they fit together — and I let the AI hold the inside of every room. What saved my brain was never a bigger brain. It was refusing to put the rooms in it.

This is still a million miles from vibe coding, and Matt is careful to say so; so am I. You don’t get to stop thinking — you move all of it to the boundaries. Every ounce of taste you were spending to keep four implementations straight in your head now goes into the doors instead: what belongs on this interface, what a caller should never have to know, where the seam honestly falls. That is not less work than reading the rooms. On a hard day it is more. But it is work the ceiling can actually hold, because a door is a thing you designed once and the room is a thing that changes every time the AI touches it. The ceiling in your skull never rose. You just stopped spending it on what a test could hold for you.

And because the pull is always to start building the room — to let the AI pour implementation while the door is still a vague idea — I don’t leave the door to whenever I happen to remember it matters. I keep it in a skill. design-an-interface makes the door the first thing rather than the last: before a line of the room exists, it drafts the interface several ways at once, radically different shapes for the same module, so I’m choosing a door on purpose instead of inheriting whatever fell out of the implementation. That order is load-bearing. Design the door well and delegating the room is safe; design it badly — too wide, too leaky, a signature that only makes sense once you already know the guts — and the gray box quietly collapses, because now you have to hold the room in your head just to use the door. The skill is how “design the interface first” stops being the thing I mean to do and becomes the thing that actually happens first.

So that’s part six. The failure was shipping more than a head can hold — the loops from part five working so well that the bottleneck slid off the machine and onto me, and a full head running a codebase the slow, tired way. The fundamental, the human payoff of every structural post before it, is the gray box: design the door, delegate the room, and take the implementation off your ceiling entirely. The skill is design-an-interface, which makes the door the first thing built instead of the last. And the artifact is a six-line function in tinkforge with 2.18 megabytes of qpdf behind it that I have genuinely stopped reading — a wall held up by a test that refuses to mock the engine and a name everyone agrees to honour, and not by a single line the compiler enforces.

There’s a word that has turned up at the end of every one of these posts, and each time I’ve let it pass like a footnote. Grill me. Say it the same way twice. Take small steps. Design the door. Every fundamental, the moment I’d learned it, I stopped trusting myself to remember and handed to a skill. Six posts, six skills, the same move each time — and that repetition was never incidental to the series. It was what the series was about. Next time, the capstone: the skill is where your hard-won judgment goes to stop being yours alone and start compounding across every project you touch — where the pre-AI sweat equity finally turns into leverage, and the last fundamental turns out to be the skill of making skills.

The gray box is Matt Pocock’s framing — design the interface, delegate the implementation, and the plain confession that it “saved my brain”; he walks it in the talk. The deep module underneath it is John Ousterhout’s, from A Philosophy of Software Design*, the same book that carried part four. The ceiling — the seven-or-so things a mind holds at once — is old cognitive-science folklore, borrowed loosely and not to be leaned on too hard. The Split door, the 2.18 megabytes of qpdf, and the wall with no compiler behind it are tinkforge’s own; I’ve only stopped reading them out loud.*

⋀⋀∫⋀⋀ Sarpa Kāvu — a serpent grove of Kerala, a patch of forest kept beside the ancestral home for the snake deities, entered only for the rites and otherwise left undisturbed.