2026-08-27 · article
Report, don't fix
You built the app yourself and your business runs on it now. Three rules that decide whether you can still explain it in six months: scope each agent, report instead of fixing, record the decision.
You built the app yourself. It works, and your business runs on it now. This is what changes next, and the three rules I run so the system can still be explained in six months.
The cost moves from building to changing
The first version gets written once. Everything after that happens on top of something people already depend on. The change is small: you ask for it, you get it, and a week later something unrelated stops working. Nowhere in that week did anyone write down what else was touched.
The moment nobody designs for
An agent working on your one-line fix notices things nobody asked it to look at. A bug two files away. Dead code. A guard that was removed at some point and never put back. It has to do something with them, and both options cost you.
If it fixes them, your one-line change touched four files, and the review you did proved nothing. If it stays quiet, what it found is gone. Nobody goes back and looks for it again on purpose. Both are normal, and neither shows up in a demo.
Three rules
Give each agent one job, and say what is not its job. Scope is the input, not a formality. An agent that has been told what it is not responsible for behaves differently from one that has only been told what to build.
Anything outside that scope gets written down, not fixed. The agent files a ticket and goes back to work. It carries a tag, the file and the line, one line on why it sits outside the current job, and one line on what it would do about it.
[tech-debt] Retry wrapper swallows the original exception
where billing/sync.py:212
why outside this ticket, which only touches the invoice template
fix re-raise with context instead of returning None
latent as long as the sync runs nightly and nobody reads its exit code
Record the decision, not only the change. If a finding can wait, the agent has to write what keeps it waiting, with the conditions named. Severity is not fixed at the moment something is found: the agent cannot see what runs next month, and I can. Six months from now the code will tell you what it does. Nothing else will tell you why it was allowed to.
The reason to make an agent report instead of fix is not tidiness. It is that the change you approved stays the change you got, and that a decision to leave something alone survives as a written decision instead of as silence.
Two rules that took longer
Every agent gets the list of findings already filed. If it sees the same thing, it does not open a second ticket, it adds a second sighting to the first one. Two agents landing on the same spot independently is the strongest priority signal I get, and two separate tickets would hide it.
One tag is for documentation. If the diagram an agent was handed says the system does something the code in front of it does not do, that is a finding too. It is the one moment when checking costs nothing, and nothing automatic ever checks a drawing.
There is also a list of what never gets filed: naming, style, “I would have done it differently”. If the list fills up with that, nobody reads it, and then it does not matter what is on it.
What it buys
Three weeks later I can say why some piece of the system looks like it does, and why something else was left alone. Both with a date. That is also the five-minute answer when a customer, an insurer or a new developer asks how the thing is governed.
You do not need a different tool for any of this. You need to require it from the one you already have.
Honest scope: this is how I build and run systems, not a product you can buy and not a compliance framework. The record is a working trail, not a certification of anything. Setting it up is a few days; getting it to behave the way you expect is a few weeks, and it keeps improving after that. It is not complicated, it just takes that long.
Built it yourself, and now changing it costs more than building it did? Bring one decision to a prepared external assessment and leave with a written recommendation. View the decision session.
Next note: two ways a self-built app fails