No. 115Product strategy

Theory Building

Your codebase is what is left over from what your engineers understand. Agents only get the leftovers.

Here are notes from an exit interview at an invented company. The engineer leaving had owned the export service for four years.

Q: Anything we should know about the export service before you go?

A: It's mostly documented. The README is current.

Q: Anything that isn't in the README?

A: The 90-day retention in the export job isn't a bug. Two enterprise contracts have a legal hold. Don't let anyone shorten it.

Q: Anything else?

A: The admin setting called "Share exports" sounds like a privacy control, and admins keep turning it off. Support knows. Don't rename it without talking to them. It'll break their help articles. Also, the CSV column order looks random. It isn't. Two customers parse it by position.

Q: Is any of that written down?

A: Some of it's in old tickets. Mostly, people just ask me.

Three weeks later, a coding agent was asked to clean up the export service. It read the README, the code and the tests, all of which were accurate. It shortened the retention to 30 days to match the rest of the platform, renamed the setting to something clearer, and sorted the CSV columns alphabetically. Every change was reasonable, and every test passed.

A computer scientist described what went missing here in 1985.

A program is a theory

Peter Naur, one of the authors of the Backus-Naur Form notation for programming language syntax, published "Programming as Theory Building" in 1985. It opens by proposing that "programming properly should be regarded as an activity by which the programmers form or achieve a certain kind of insight, a theory, of the matters at hand." That, he says, is "in contrast to what appears to be a more common notion, that programming should be regarded as a production of a program and certain other texts."

He takes the word "theory" from the philosopher Gilbert Ryle. A theory in this sense is "the knowledge a person must have in order not only to do certain things intelligently but also to explain them, to answer queries about them, to argue about them, and so forth." For a program, that means a programmer who has the theory can do three things the code alone can't. They can explain how the program relates to the part of the world it handles. They "can explain why each part of the program is what it is." And they can "respond constructively to any demand for a modification of the program so as to support the affairs of the world in a new manner."

His central claim is about where that knowledge lives. Programming "primarily must be the programmers' building up knowledge of a certain kind, knowledge taken to be basically the programmers' immediate possession, any documentation being an auxiliary, secondary product."

Documentation is not enough

Naur's evidence is two cases from real projects. In the first, a group B extended a compiler that group A had built, with "full documentation, including annotated program texts and much additional written design discussion, and also personal advice." Group B's proposed changes kept missing facilities that were "not only inherent in the structure of the existing compiler but were discussed at length in its documentation," and relied instead on "patches that effectively destroyed its power and simplicity." Group A spotted the problems instantly. Naur's conclusion: "the full program text and additional documentation is insufficient in conveying to even the highly motivated group B the deeper insight into the design."

The second case is a large real-time system, where the programmers who had lived with it for years diagnosed faults easily, and other teams with full documentation kept getting stuck. "The conclusion seems inescapable that at least with certain kinds of large programs, the continued adaptation, modification, and correction of errors in them, is essentially dependent on a certain kind of knowledge possessed by a group of programmers who are closely and continuously connected with them."

He explains why changes made without the theory do damage even when they work. A modification "may usually be realized in many different ways, all correct," but some fit the program's theory and others "may be wholly inconsistent with that theory, perhaps having the character of unintegrated patches on the main part of the program." Only someone who holds the theory can tell them apart.

Life, death and revival

Naur's starkest section follows from this. "The death of a program happens when the programmer team possessing its theory is dissolved. A dead program may continue to be used for execution in a computer and to produce useful results. The actual state of death becomes visible when demands for modifications of the program cannot be intelligently answered."

Bringing a program back means a new team rebuilding the theory, and Naur is blunt about how hard that is. Reading is not enough: "it is insufficient that he or she has the opportunity to become familiar with the program text and other documentation." A new programmer needs "to work in close contact with the programmers who already possess the theory." And "reestablishing the theory of a program merely from the documentation, is strictly impossible."

Coding agents are group B

The framing that follows is ours, not Naur's, but his cases describe the agent in the opening closely. A coding agent arrives at every task in group B's position: full program text, whatever documentation exists, and none of the theory. It produces changes that pass every test and can still break what the theory explains, which is how the program relates to the world it handles. The retention change, the rename and the column sort each passed every test, and each broke something the departed engineer could have explained: a legal hold, support's help articles, and two customers' parsers.

Agents change two things at once. They make modifications much cheaper to produce, which means more of them, made faster, by something that holds none of the theory. And they shift the people who do hold it away from the code. Our essay on the modern product development lifecycle describes where that leads: "The work now piles up at the same review gates, waiting on people." In Naur's terms, the people at those gates are the theory, and they are now reviewing more changes than they could ever have written.

We've written about what leaks through when an agent abstracts away the code and about knowledge that never sits in one place. Naur's version is sharper than either. Some of what an agent needs isn't missing from the documentation by accident. On his account, it can't be put there at all.

Where Brief fits: keeping changes close to the people who hold the theory

Brief is the product strategy agent. The homepage says it "captures decisions where they happen, connects them into one graph, and acts on them." Naur would say Brief can't hold a program's theory, and on his terms he is right. What it can do is narrower: keep the parts of the theory that can be stated where agents will find them, and route the rest back to the people who have it.

The statable part gets written down. Naur's second ability is explaining "why each part of the program is what it is." Some of those explanations are product decisions that fit in a sentence. In the Brief app, recording a decision requires both What was decided? and Why? before Record Decision will save it, and a decision can also carry Tags and a Re-evaluate when condition. "Exports are retained for 90 days, because two enterprise contracts include a legal hold" is one line of the departing engineer's theory. It isn't the theory itself. It is the part that would have stopped the agent.

It is read from where it gets said. Most of the exit interview's answers had been said before, in tickets and threads, and never collected. The homepage says Brief "reads decisions from Slack, Jira, Confluence, and GitLab, self-hosted included." A decision explained in a ticket doesn't have to wait for an exit interview to be found.

Agents check before they patch. Coding agents set up with Brief search the recorded decisions before they start work, and ask Brief to check significant changes with brief_ask in check mode, which compares a planned change against existing decisions and flags conflicts. An agent planning to shorten export retention to 30 days can find the legal hold decision first. That is much narrower than group A spotting every bad patch at a glance. It only catches conflicts with what has been recorded. People can run the same check with brief ask --mode check.

Open questions go to whoever holds the theory. Naur's remedy for a new programmer is close contact with the people who already have the theory. When an agent or engineer hits a question the record doesn't answer, Propose turns it into a pending decision and can name Who should decide?, so the question is recorded against a person. With the user's approval, an agent can record one too, and agents can call brief_list_pending_decisions to see what is waiting. When a decision is pending, an agent can hold. The homepage shows an agent asked to add per-seat pricing to the checkout API learning that D-241, the seat-based pricing decision, is pending, and replying: "Holding the pricing change until D-241 is decided."

The theory's revisions leave a trace. Naur says a program has to change as the world it serves changes. When a decision changes, its History shows its status changes, so the next person can see that the reason moved, not just the code.

None of this answers Naur's hardest claim. A recorded decision is documentation, and he held that rebuilding a theory "merely from the documentation, is strictly impossible." Brief can't keep a program alive after the team that understands it leaves, and a decision nobody recorded gives an agent nothing to check against. When nothing has been recorded, check mode finds no conflict, and the agent goes ahead on the code alone. What Brief changes is how much of the theory is lost when someone leaves, and whether agents ask the people who still hold the rest.

Naur said a program dies when the team holding its theory is dissolved, even if it keeps running. If the engineers who know why your billing code looks the way it does left tomorrow, what would your agents still know?

Objections

Objection 1

What is "Programming as Theory Building"?

"Programming as Theory Building" is a 1985 article by Peter Naur. It argues that programming "should be regarded as an activity by which the programmers form or achieve a certain kind of insight, a theory, of the matters at hand," and that program text and documentation are secondary to that theory, which lives in the programmers themselves.

Objection 2

What does Naur mean by a theory?

Naur borrows the idea from the philosopher Gilbert Ryle. A theory is "the knowledge a person must have in order not only to do certain things intelligently but also to explain them, to answer queries about them, to argue about them, and so forth." A programmer with the theory of a program can explain how it relates to the world, why each part is the way it is, and how to change it well.

Objection 3

What is program death in Naur's theory building view?

Naur wrote that "The death of a program happens when the programmer team possessing its theory is dissolved." The program can keep running and producing results, but the death "becomes visible when demands for modifications of the program cannot be intelligently answered." He argued that rebuilding the theory from documentation alone is "strictly impossible."

Objection 4

How does theory building apply to AI coding agents?

A coding agent works from the program text and whatever documentation exists, without the theory the original programmers hold. It can make changes that pass every test but break what the theory explains, such as a contract that depends on a setting or customers that depend on a file format.

Objection 5

How does Brief help when the theory lives in people's heads?

Brief records the parts of a team's reasoning that can be stated as decisions with a Why?, including decisions it reads from Slack, Jira, Confluence and GitLab. Coding agents set up with Brief search recorded decisions before they start work and use check mode to flag conflicts in significant changes, and open questions can be proposed as pending decisions that name who should decide. Brief cannot hold a program's full theory; it keeps the statable parts and points the rest back to people.


Previously
No. 114

The Knowledge Problem

Nobody on your team knows everything your product has decided. Routing it all through one meeting won’t change that.