Every Abstraction Costs One Detail
Written later and filed to this date, as part of filling in every day of the year.
A sentence I wrote into a comment at the top of a small file: a lever with a silent exemption is not a lever. I like it. It is the kind of line that gets quoted back. It also means nothing on its own, and the thing that makes it mean something is the line before it: the pause command stopped the half of the workspace written in one language and left the half that restarts services running, because the second half could not read the flag.
That pair is the unit I write in now, and the rule is the title: every abstraction is paid for with one concrete detail. The abstraction is the sentence you would say at a whiteboard. The detail is the thing a stranger could go and check: a number, a quoted line, a timestamp, a filename, the string a program actually printed. One pays for the other. A piece on this site is allowed as many abstractions as it has details to spend on them, and no more.
The test
Delete the detail and re-read the sentence. If it still sounds true, it was a slogan, and slogans sound true by construction. “Capacity is not exclusion” sounds true. “With the cap at five, four enabled projects working and one unenrolled worker alive, the fleet read four slots occupied and admitted a sixth agent into a repository that already had one” is true, and the slogan is only the name you give it afterwards so you can carry it to the next incident.
Then run the test the other way. Delete the abstraction and re-read the detail. If the detail survives alone, you have a changelog entry: it happened, and the reader has no idea why it was worth telling them. They will supply an abstraction of their own, and it will be worse than yours, because you were there.
The rule is not “add examples”. An example illustrates a point already made. A detail is where the point came from, and the piece should be able to show the moment the sentence was earned.
Where it bites
Commit messages, first. A subject that says a thing was improved is all abstraction; the diff underneath is all detail; the body is where the two are supposed to meet, and it is the part most often left empty. Three identical subjects in a row in one of my older repositories, each hiding a different change, are the purest form of the failure: the abstraction had been written once and reused, and the details had nowhere to go.
Status messages. A producer that posts “warning” has paid nothing. A producer that posts “waiting on you: run the apply script” has named exactly what a person does next, and a dashboard can sort by that.
Notes about old work. A note handed to me described one of my earlier repositories as an early attempt at agents that run unattended. The log shows a clicker game. The note was an abstraction with no detail attached, and an abstraction with no detail attached cannot be wrong, which is precisely the problem with it: nothing in it could be checked, so nothing in it had been.
Numbers. A number in prose is a claim and a number in a table is a fact, and the difference is that the table shows where the number came from. “Over a thousand candidates” is an abstraction with a digit in it. “1,388 candidates, led by git status and the type checker” is a detail, because the two names tell you what the counter was actually counting, and from them you can derive the abstraction yourself: it was counting tool use, not friction.
One, not several
The number in the rule matters as much as the rule. One detail per abstraction. Two is a list. Five is a report, and the reader who wanted the sentence has to dig it out from under evidence they did not ask for. When a draft of mine reads like a report, the diagnosis is almost always that an abstraction was paid for three times over, and the cure is to keep the strongest detail and spend the others elsewhere or not at all.
The reverse ratio is the more common failure in writing about systems, because systems produce details for free and abstractions only when someone sits still. A log file is nothing but details. The work is deciding which one line in it is the one that cost something, and then saying, once, what it bought.
The template my build agents are scoped from says the same thing in its first section, under the heading for what exists now: be concrete, name files, name the missing capability, name the manual chore. It is advice to a program about to be handed a job, and it turns out to be the whole of the advice for a person about to be handed a page.