--- title: "I Was Shipping Faster Than I Could Understand It" subtitle: "I run about a dozen repositories with an AI, and one week I realized I could no longer explain half of what had shipped. So I stopped adding features and built one workflow every repo runs the same way: a doctor that fires when I sit down, a contract that keeps an unattended run honest, and a rule that nothing lands until a human who still understands it says so." author: "Tjakoen Stolk" status: DRAFT type: note date: 2026-07-30 readingTime: "~8 min" tags: [ai, workflow, process, developer-tools, standards] summary: > How I got back on top of AI-assisted work across a dozen repos: one shared workflow instead of a dozen improvised ones. A work-triggered heartbeat (a doctor at every session start, CI on every push) that makes skipped chores visible, an accountability contract (a run ledger, declared rails, and verification by a second pass) that keeps an unattended run honest, and a documentation discipline borrowed from aerospace manuals and from Addy Osmani's writing on loop engineering. One person applying the shape the field agrees on, honest that it isn't proof it scales to a team. --- ## 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.](ten-times-zero.md) 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. I have [written before](where-were-we.md) about opening a chat every morning and asking the machine to please describe, in prose, what it thought the plan was. 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](https://addyosmani.com/blog/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. ## 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. A push, or a session starts The doctor surfaces what's due drift, a stale audit, missing tests A session drafts a fix on a branch A second pass verifies it never the one that wrote it I land it nothing lands unread *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. 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. --- *The [judgment is human](ten-times-zero.md). The typing, by design, is not.*