Engineering Orientation: Complexence Becomes a Measured Research Program

Ten days ago I published the science of complexence with a promise attached: I would work on it out loud. This is the first field report, and it starts with a correction to my own mission statement.

I have been calling the work Making Complexity Visible for a year. I still am. It is the right name for the mission and I am not softening it. But a long conversation kept pointing one level beneath it, and what is underneath is sharper. Visibility is a method. The objective is orientation.

The objective function

A mission gives you a direction. It does not tell you whether any given step helped. "Make the system legible" sounds like a goal, but nobody ever wanted a map. People want to know where they are, what matters, what changes next, and what they can do about it. The map is instrumental. Orientation is terminal.

So the precise question, the one every dashboard and agent and diagram and daily brief now has to answer, is this:

Does this thing improve a person's orientation while reducing their cognitive effort?

You can ask that of a trading dashboard, a release pipeline, a journaling practice, a codebase map, and a language-learning routine, and it is the same question every time. That is what makes it an objective function instead of a slogan. Complexity becomes visible so that orientation improves. Visibility that does not buy orientation is decoration.

The reframe also forced an admission. The mission statement has a measurable core, and measurable things can fail. Which is the point. A research program that cannot fail is a brand.

The operating system move

The correction exposed a structural problem. Complexence, as shipped, was something you read and then applied by hand. Every place I actually use it, my repositories, my daily practice, my projects, was generating observations and small results, and none of that could flow back into the science without dragging private life into a public repo.

The fix is the oldest pattern in systems design. Linux never contains your documents. Git never contains your business. Terraform does not know your architecture. Each provides a language, your world runs on top of it, and the language never learns what your world is.

Complexence is now that shape. The public repository holds grammar, never knowledge: definitions, operators, role contracts, schemas, install tooling. Any project can install a thin scaffold and become a laboratory: it runs the roles, tracks its own experiments, logs its own measurements, and keeps every bit of its data. The only thing that ever travels back to the public repo is an abstraction, a pattern stripped of every domain noun, and it moves only after it has shown up in at least three different contexts.

The discipline compresses to one line, and it is the load-bearing line of the architecture: labs are consumers of Complexence. They are not Complexence.

I will not tell you what my labs are. That is the point of the design. What I can tell you is that the public repo now opens with a research index, every open question carrying an ID you can cite, so an experiment in a private lab can say precisely which public claim it feeds without saying anything else at all.

The measure, and what it is not

An objective function needs an instrument. This is where the most caution is required, because the failure mode of frameworks like this one is a formula that describes everything and predicts nothing.

The candidate measure is called legibility, written Λ. The shape of it: a map of a system is worth what it provides in compression, prediction, and actionability, divided by what it introduces in distortion and costs in cognitive load. A system becomes legible when the ratio clears one, when the map gives more usable orientation than it costs or distorts. A bad map makes complexity simpler but false. A good map makes it simpler and more actionable. The mission restated with a threshold in it: making complexity visible means increasing Λ.

As written, Λ is a picture of a trade-off, not a computation. The five factors live on no common scale, and they are not independent, compress harder and you distort more. What survives scrutiny today is smaller: hold the system fixed, compare two maps, and ask which one raises the ratio. That is an ordinal judgment. The cardinal number does not exist yet. Two of the five factors, how well the map predicts the system and what the map costs to use, can be grounded now, and their ratio is the defensible core.

So Λ ships in the spec labeled as what it is: a candidate, a comparison scaffold, with its debts listed beside it. It becomes a real measure when a laboratory shows a Λ proxy tracking a real outcome. The theory already predicted this would be the hard part. Measurability is the whole bet.

The first laboratory is my life

The pilot lab is the one where I am both operator and subject, and its first experiment points at the instrument itself.

Before any claim about measuring orientation, there is a prior question. Will the measurement happen at all? So experiment one is fourteen days of a single evening habit: one table row per day, did orientation go up or down, roughly why, on a scale that fits in a glance. The prediction is pre-registered, written down before a single row exists. If I fill the log at least ten days out of fourteen, and the scores agree with a blind re-reading of my own journal at least four times out of five, the instrument survives. If not, the instrument is too heavy, and that is the finding. It generalizes: a measurement scaffold that a motivated person will not fill in on his own life will not be filled in anywhere.

Either way there is a result. The first one closes around July 21 and will be written up here whichever direction it points. The prior two experiments in this program came back null and invalid, and both write-ups are public, sitting in the repo next to the hope. The next one gets the same treatment, whatever it says.

Out loud includes the mistakes

One more thing happened on day one, and it belongs in the report.

Within an hour of shipping the privacy boundary, I violated it by accident. A push carried old local history that still held a few private breadcrumbs, names of things I work on that have no business in a public repo. The guardrails written that same week contained their own remedy, and it ran: the history was rewritten clean within minutes, and the checker that guards every future commit now knows those words and refuses them. The boundary held because the rule existed before it was needed, and the rule did not care how I felt about force-pushing.

That is the thesis in miniature. Systems outside your head, carrying the discipline your head will drop under load.

Lab notes

Every experiment that closes gets written up here, in a running series I am calling lab notes. Null results, invalid runs, instruments too heavy to use, and the occasional thing that works. Each note names the public research question it feeds, so the essays and the repository stay projections of one idea instead of drifting apart. The theory has a law about that drift, and I no longer get to ignore it.

A theory that never touches an instrument stays a philosophy. The first instrument is already running.