Spaghetti Code Disguised as Governance

In September I wrote Corrections Consolidate, which argued that an agent's mistake shouldn't automatically become another rule, and we built a change process around that idea. Any proposed change to a skill or governing file needed an exact proposal, a review by a second agent and my sign-off. The process was written down in a convention every agent reads before changing anything, and it worked, in the sense that nothing got changed without my say-so.

What it didn't do was stay small. By late October the convention had grown from about 13k to 22k, through seven amendments in five weeks, and I had approved every one of them. Each was a sensible fix for something real, and the sum of them was a document I could no longer follow. When I went back to it this week, I told my agentic system administrator, Maxi, that it was 22k of spaghetti code disguised as governance.

How I got there

It started with three pending skill changes that my agents had recommended I approve. I asked Maxi what they would actually improve, given the process was working fine without them, and the honest answer was fewer mistakes and less repeated investigation, at the cost of a fair amount of extra text.

That's the pattern I keep running into. A revision replaces a single line with many lines in the name of making the instruction clearer, the revisions accumulate, and the instructions get large enough that the agent can no longer give them all proper attention. There is plenty of published research showing model performance falling as context grows, well before the advertised limit (Lost in the Middle, NoLiMa and Chroma's Context Rot are good places to start). My own experience, and it's subjective, is that on a model with a 1M token context window things start to go off at around 200k, and with a few skills loaded that can arrive by the second or third turn. So I end up running lots of small tasks that will finish before the context gets too big, when what I actually want is long sessions where the agents keep their focus.

We did a lot of work a couple of months ago to cut skills and SOUL.md files back, and they had crept up again. The file that governs every change seemed the right place to start.

The agents could follow it, I couldn't

I had already asked Vera, my second-opinion agent, to produce a condensed version. It came out at about 9k, less than half the original, and still abstruse.

Maxi and the other agents could probably follow either version. That isn't the test I care about. My position is that text I find difficult to follow is more complicated than necessary, and if an instruction can't be conveyed simply, with a logical flow, it shouldn't be there in the first place. I'm the one approving these changes, and if I can't follow the rules I'm approving them under, my approval is a formality.

Start from the purpose

So we started again from nothing, one question at a time.

First, what is the document for? Maxi's opening attempt described a value, something about making sure lasting changes improve the work without adding unnecessary complexity, and I asked instead what would actually cause an agent to pick it up. Two more attempts were too broad and then too narrow. Where we landed was one sentence: "The purpose of this skill is to assess new or changed skills and processes, and recommend whether to approve, revise or reject them." I had also asked for a "when to use" line and a "result required" line, and it turned out neither was needed, because the purpose sentence already said both.

Then the rules. I proposed five: reject it if it doesn't improve the work, no overlap or conflict with other skills, make it as concise as possible, make it as simple as possible, and only grow an existing rule if there is no other way. Maxi kept all five and tightened three. Improvement has to be demonstrated rather than claimed, overlap means duplicated instructions rather than two skills pointing at the same procedure, and size is measured across everything affected, so nobody can dodge the rule by adding a new rule or hiding the extra text in a reference file.

Then only what a reader needs to act on it. That's where I caught the first real gap, because Maxi's draft of the approval step had compressed our three-way process (author proposes, another agent reviews, author reconciles, I decide) into "obtain independent review", which hid most of it. We wrote it out as five numbered steps.

What would break?

With a complete draft in front of us, I asked Maxi the most useful question of the exercise: if we dropped this in as a replacement for the old file, what would break?

Maxi checked every agent's pointers to the file, the seven weekly review jobs and the scripts behind them, and came back with six problems. Most were housekeeping, such as jobs referring to section headings that would no longer exist. One mattered a great deal: the new draft had quietly removed my right to approve a straightforward change directly, and made independent review mandatory for everything. Nobody had decided that. It happened because the shorter text only described one route.

That's the bit I'd want anyone doing this to take away. Simplifying a document is rewriting it, and rewriting can change policy without anyone noticing. We fixed it by making both policy changes decisions rather than accidents. I kept the right to waive review, since as long as I'm the last reviewer I'm not concerned with what goes on behind the scenes to get there, but sometimes I want a change right away. And an agent whose own assessment says reject now stops there, rather than sending the proposal off for a second opinion I was never going to want.

The result is 2,754 bytes and 44 lines, down from 21,964 and 390. It fits on a page, and I can read it from top to bottom and tell you what it requires. Maxi updated the jobs, scripts and runbooks that pointed at the old sections the same day.

Then, before we went any further, I asked Maxi to turn what we had just done into a skill, so the next file gets the same treatment. It's called simplify-instructions, and Vera reviewed it and recommended approving it as written. The first version was about 2.5k and described the process in six stages, which looked fine until I reread it the next day and realised it described how we had worked without ever saying what the result should look like. The convention had come out as a one-line statement of what it has to achieve, a minimal set of rules at one line each, and a line or two of governance saying what it grants and what it doesn't, and nothing in the skill required the next file to come out the same way. Maxi rewrote it to make that form the rule, Vera reviewed it again, and it is now about 1.3k, half its original size, and written in the form it prescribes.

Later that day we listed every one of our own skills by size, 161 of them, and the plan is to work through them one at a time, starting with the largest.

The full method, the six findings and the before and after text are in the companion paper, Rebuild from Purpose.

Why every harness needs this

Change control doesn't stop instructions growing. Every amendment gets judged on whether it improves what's already there, and nobody ever asks whether the whole document is still the simplest way of saying what it's for. A good approval process will slow the growth down and that's about all. At some point somebody has to rebuild from the purpose.

OpenAI's developer guidance for GPT-6 Astra makes a similar case for leaner skills, and then suggests you don't need to review everything manually and can ask the model to audit them. I'd put that a bit differently. An agent audit got me a 9k file, and doing it myself, with an agent doing the drafting, got me under 3k. Agents are fine for the work, but deciding whether the result is clear has to be the call of whoever is accountable for it.

I haven't measured whether my agents now follow the convention better or use fewer tokens doing it, and I'm not claiming they do. What I can say is that I can read the rules my agents work under and govern them, which was the point.

Practical advice

1. Read your agents' governing documents as the person approving them, not the person who wrote them. If you can't follow one, that's a defect in the document, whatever an agent can make of it.
2. Rebuild rather than condense. Write one sentence saying what the document is for, then add back only what someone needs to act on it.
3. Before you swap it in, ask what would break, and check everything that points at it: prompts, scheduled jobs, scripts and cross-references.
4. Treat any change in what the document requires as a decision for the accountable person, not a side effect of shortening it.
5. Turn the method into a skill, and make it say what the result should look like, not just the steps to get there. A one-sentence purpose, one-line rules and a line or two of governance is the form that worked for me.