I Was Shipping Faster Than I Could Understand It

The week I couldn't explain my own work

There was a week where I looked at what had shipped across my repositories and could not, off the top of my head, explain half of it. It all worked. The tests were green. And I could feel a gap opening between the code that existed and the code I actually understood.

That is a strange kind of fear, because on paper it looks like success. I run about a dozen repositories now, mostly alone, mostly with an AI doing a real share of the typing. The output went up and up. But output going up while comprehension stays flat is not a productivity win. It is debt with a nice green dashboard on top, and you can run a repo you no longer understand right up until the day you have to fix it.

I have a maxim for this, worn smooth from teaching it: ten times zero is still zero. The AI multiplies what I bring. If what I bring is a shrinking understanding of my own estate, then the faster it goes, the worse the problem gets. The speed was never the thing to protect. The comprehension was.

First, an honest look at what I was doing wrong

The embarrassing part is that I had built the trap myself, one reasonable decision at a time.

Every repo worked a little differently. This one kept its plans in a document, that one in my head, a third in whatever the last session's handoff prompt happened to capture. Every session opened with me asking the machine where we were, and the machine reading four notebooks to work out an answer it had worked out yesterday. That was one symptom. The deeper one was that "how I work with AI here" was a different answer in every folder, so nothing I learned in one repo made the next one safer. Twelve repos, twelve slightly different workflows, and me the only thing they had in common. One person can run a dozen repos only if the twelfth one behaves exactly like the first.

So I stopped building features and read

Instead of adding more, I went and read the people who had thought about this harder than I had.

The most useful was Addy Osmani's writing on what he calls loop engineering: the case that durable AI work is built from a small set of reusable parts, not a clever prompt. His companion book carries the harder half, the "70 percent problem," where an AI gets you most of the way and the last stretch is exactly where unmanaged work rots, and the argument that quality gates are not optional. That is the writing that named the fear I already had.

The other source was older and stranger: a documentation standard from aerospace, the kind written decades before the web so that an aircraft maintenance manual reads the same in every hangar on earth. Plain verbs, one name for each thing, no decorative fog. The surprise is how well that discipline lands on a language model. Hand a machine a system to follow and it writes like it. Hand it a wish and it writes like a wish. Writing things down the same way every time turns out to be the whole game, whether the reader is a mechanic or a model.

So I did not invent a workflow. I stole the shape the field already agreed on, and made every one of my repos run it.

The first thing I fixed was where the plan lives

The obvious move would have been a better handoff prompt. I went the other way and took the plan out of the conversation entirely.

One plan per markdown file, in a plans folder, with a small frontmatter: an id, a status (todo, doing, done, blocked), an optional track, what it depends on, what code it touches, and whose plan it is. The body is prose and a checklist. That is the whole format, and the smallness is the design.

The AI already edits markdown. It is the most native motion it has. So keeping a plan current costs it one line: flip the status field in the file it is already working in. No plugin, no API, no new tool for the machine to learn. The discipline rides on a motion that already exists, which is the only kind of discipline that survives a long session.

Then a separate little tool reads that folder and renders it as a kanban board in the browser, built out of my own design system. The board writes nothing. It is a window, not a database. Delete the tool and the plans are still sitting there as readable markdown in git, which is exactly where they were all along. I called it PROOF, because the stack it joins is already named batch, grain and mill, and I have committed to the bread thing well past the point of dignity.

The output has provenance. The intent has none.

That line is why I bothered. I had spent months on a design system where the machine's work is visible on the surface: text the AI wrote renders with a grain to it, text a human settled renders clean. The whole thesis is that you should be able to look at software and see whose hand did what. Meanwhile the most important artifact in the room, the plan, lived wherever the last conversation happened to leave it. I could watch the AI's hands on the keys and still had to ask it what it thought it was doing.

The first thing on that board was the plan for building the board, which is either a good sign or a closed loop with delusions of grandeur. Either way it has been a while since a session opened with anyone asking where we were.

I should be honest about who this helps, because the split is lopsided. The AI never looks at the board. Its share is real but modest: a cheaper start to each session, a ground truth two parallel sessions cannot argue about, and plans forced into pieces small enough to have a status at all. The rest lands on me. I get to glance at a wall instead of interrogating a chat window. If I sold this as an AI productivity tool I would be lying about which side of it the value falls on.

The wall fixed where the plan lives. It did nothing about the chores nobody flips a status field for.

One heartbeat, and it fires while I'm already working

The chores that get skipped are the boring recurring ones: the end-to-end suite, the lint pass, the audit that is three weeks overdue. The fix is not discipline, because discipline is exactly the thing that fails at 1am. The fix is to make skipping visible.

So there is a heartbeat, and the important choice was when it beats. Not at 3am. A robot that finds a problem in the middle of the night has nobody to hand it to, and its report competes with every other notification I ignore. The heartbeat fires when I am already working: a check on every push, and a doctor as the first thing every session does when I sit down. It is not clever. It is grep, exit codes, and file-age math. Its whole job is to put the due work in front of the one person who is about to change the code anyway.

The loop drafts. The human, who still understands the code, lands.

The little program that runs the checks is part of my own tooling now, a doctor I can point at any repo to ask "what is out of shape here." A green doctor is what "day one done" means for a new repo. A red one is a to-do list I did not have to remember to write.

The contract that keeps an unattended run honest

The heartbeat surfaces the work. A separate thing had to keep the doing of it honest, because the moment an AI touches code without me watching every keystroke, "trust me" is carrying all the weight. So there is a contract, and it is deliberately mechanical, a checklist a run has to satisfy rather than a feeling I have about it.

• Evidence or it didn't happen. A run claims the plan item before it edits, leaves a short note at each real decision, and closes with a report that carries the actual gate output, not the phrase "tests pass." A report that lists only wins is a report that is hiding something. It also has to say what it did not do, and what needs my eyes.
• A declared envelope. Before an unattended run starts, it states the files it may touch and the lines it may not cross: no merge, no push to the main branch, no deletes, nothing that reaches the outside world. The loop drafts. A human lands. Those are absolute, not defaults.
• No grading your own homework. A change is verified by a pass that did not write it. The author's own "looks right" does not count, which is the one rule that keeps a fast loop from confidently shipping its own mistakes. It is the same wall I put between the AI and my students, just pointed at my own code.

None of it is exotic. It is human verification, written down so it happens the same way every time instead of the way I feel like doing it at midnight.

What I am honest about

This is one person's estate, not a study. Two things I will not overclaim.

It is not proof it scales to a team. Everything here works because there is exactly one human in the loop who still understands the code and gates every merge. Whether the same shape holds when there are five of those humans is a real open question, and I have not earned an answer to it yet. And the books I leaned on are still being read as I write this, so this is a living base, not a finished theory. I am reporting a change that worked for me, with the seams showing.

A correction, dated the twentieth of August. The subtitle of this note says every one of my repositories runs the same workflow, and I wrote that sentence believing it. Three weeks later I queried my own session store and found the doctor had run once in a hundred and sixty-five sessions in my largest client project, and not at all in three of the others. It was not a discipline problem. The script could not find its own program from any directory except the one it was written beside, so it announced itself unavailable and exited quietly with a success code. The path is fixed and the rollout is real now, but a rollout is not a result, which is exactly the mistake the sentence above makes. I am leaving it as published rather than editing it, because the gap between what I claimed and what was running is the more useful artifact. The whole thing, including the day I spent explaining the silence with a theory about discipline, is in The Check Ran Once in 165 Sessions.

I also chose not to build the one piece everyone assumes you want: the scheduled agent that runs at night. I do not have one, on purpose. A check I will actually act on is a check that fires while I am already at the desk. A check that fires while I am asleep is a report I will read the way I read every other 3am notification, which is not at all.

Where that leaves me

The point of all this was never to ship more. It was to stop shipping things I could not explain. So now, when I sit down, the doctor tells me what is out of shape before I touch anything. When a run finishes, it hands me evidence instead of a shrug. And nothing reaches the main branch of any repo until I, the one human who still has to understand it, sign off.

I can explain what shipped this week again. That is the whole win, and it is the same one from the classroom, pointed at myself: the multiplier is real, and it is only worth having if you stay worth multiplying.

Since writing this I have taken the same shape and asked what it would look like at the scale of an engineering organization rather than one person with a dozen repositories. That is Everybody Wants the Agent: the same argument about verification and legibility, turned into a roadmap, with the research behind it and the parts that broke on me left in.

The judgment is human. The typing, by design, is not.