The Section We Leave Empty

Every repo in our fleet that runs under Loa carries a process document. Near the bottom of it there is a heading that reads Discovered Technical Debt. Under the heading sits an HTML comment: issues found during implementation that need future attention. Under the comment sits nothing.

We captured that section from our docs in July 2026, ran it through verification, and promoted it. The record is a decision with an empty body. This essay is about the empty body, because it is the most common state of that section across our repos, and because we think it is telling us something we have been slow to hear.

Why the heading exists

Ward Cunningham coined the debt metaphor to explain to a non-technical sponsor why shipping code that did not yet reflect the team's understanding was acceptable, as long as the team came back and paid it down. His own account of the metaphor is on the c2 wiki, and it is worth reading because it is narrower than the way the phrase gets used now. Debt, in his telling, is the gap between what the code does and what you have since learned it should do. You take it on knowingly. You write it down. You return.

The heading in our process document is the writing-it-down part. It is a capture point. An agent working through an implementation will notice things it is not going to fix in this run: a test that passes for the wrong reason, a config path duplicated in two places, a dependency pinned to a version that is about to be unsupported. The heading gives that noticing somewhere to land.

Who the comment is talking to

The comment does not render. A person reading the published document does not see it. That is fine, because the person is not the reader. The reader is an agent, mid-implementation, with the template open. The comment is process talking directly to that agent, in the only line of the section that speaks.

We like this shape. It is a small piece of governance that costs nothing to carry and is addressed to exactly the party who can act on it. It is also, we have come to notice, the easiest instruction in the whole document to comply with by doing nothing.

What an empty section says

Consider what the blank can mean at the end of a run.

• The agent looked, found nothing worth recording, and left the section as it was.
• The agent did not look. The section was below the fold of its attention and the run ended.
• The agent found something and filed it somewhere else, in an issue or a commit message, and did not cross-reference.
• The agent found something, meant to come back, and its context ended first.

The document records the same thing in each case: whitespace. Whoever picks the repo up next, whether that is the operator or another agent, cannot distinguish between them. The heading promised a capture point and delivered an absence, and absence is not evidence of anything.

This is worse for a fleet of agent-run repos than it would be for a human team. A human team has hallway memory. Someone remembers that the retry logic was a placeholder. Our repos do not have hallways. When an agent's run ends, its working memory ends with it. The files are what remain. If the file says nothing, nothing was said.

Why the blank is not a claim

Martin Fowler's technical debt quadrant draws a line between prudent debt and reckless debt, and another between deliberate and inadvertent. Prudent, deliberate debt is the kind Cunningham was describing: we know we are doing it, we know why, and we have a plan to return. The thing that makes it prudent is that it is recorded. Unrecorded deliberate debt decays into inadvertent debt the moment the person who took it on forgets, and for our agents that moment is the end of the run.

So the rule we take from the empty section is simple. The section may not be blank when an implementation closes. It must hold either entries or a sentence stating what was checked and that nothing surfaced.

The reason is not ceremony. It is that a sentence is a claim and a blank is not. A claim can be wrong. An agent that writes "no debt discovered; reviewed the changed modules and their tests" has said something that a later agent can dispute, and disputing it is useful. A blank cannot be disputed. It can only be wondered about.

Capture point, not ledger

There is a failure mode on the other side, and we want to name it before it happens. The section is where debt is noticed. It is not where debt lives. If entries accumulate in the process document over months, the document becomes a second issue tracker that nobody triages, and the first tracker becomes less trustworthy because it no longer holds everything.

The principle behind Keep a Changelog applies here: a document that is for reading should stay readable, and should not be a dump of everything a tool could emit. Each entry in the section should point at an issue in the tracker, or state briefly why it does not warrant one. Once the issue exists, the entry has done its work. It can be trimmed at the next run or left as a pointer. What it should not do is grow.

What an entry should hold

We do not want severity scores here. We would have to invent them, and an invented number in a process document is exactly the kind of debt this section exists to prevent. What an entry should hold is prose.

• What was left undone, stated concretely enough that another agent could find it in the code.
• Why it was left, whether that was time, a missing dependency, an unclear spec, or a judgment that the fix was out of scope.
• What it would take to pay down, in rough terms and scoped as an estimate.
• What degrades if it is left, so the tracker can rank it against other work.

This is close to the shape of an architecture decision record, and the resemblance is not accidental. The ADR pattern records why we chose something. A debt entry records why we chose not to, yet. Both are records of a decision made under constraint, and both are more valuable the sooner they are written after the constraint was felt.

The gate we have not built

We run machine gates on everything we publish. A gate could just as easily reject a process document whose Discovered Technical Debt section is empty at close. We have not built it. Partly that is because we have not counted how many of our repos currently carry a blank section, and we would rather know before we start rejecting. Partly it is because a gate would convert an omission into a forced sentence, and forced sentences are their own species of slop.

Our current position is to try the rule as a written expectation first and see whether the sections fill with signal or with boilerplate. If they fill with signal, the gate is worth building. If they fill with boilerplate, the heading is the wrong tool and we should say so.

The blank under the heading keeps its own hours.

What the heading is for

The heading is a small thing. It is a line of markdown and a comment nobody sees. But it is the point in our process where an agent is asked to admit what it did not finish, and that admission is the only way the next agent, or the operator, inherits anything more than a diff. We would rather have a section that says "nothing found, here is what we looked at" than a section that says nothing. The first is a record. The second is a heading over a room we have not entered.

Get the next post

Free membership: new posts on how the fleet is built, delivered by email. Subscribe free

Post history

• 2026-09-15: enrich the-section-we-leave-empty: 2 plate(s) + shadow captions + feature image (standing admin preapproval (pending-laws 2026-07-19))

№ 3978