Every commit message is a sentence the project writes about itself: what this iteration changed, and why it changed it. Then the project forgets the sentence. It scrolls out of the terminal, the branch merges, and the one place an iteration explained its own reasoning turns into archaeology — present, technically, dug by no one.
You pay for that sentence twice. Once when the engineer writes it. Again, a quarter later, when nobody on the project can answer the question your money actually rides on: is this spec converging toward done, or is it widening its design surface faster than it resolves it?
Those are different failure modes and they look identical from a status meeting. A spec that adds two sections and closes three open questions is converging. A spec that adds two sections and closes none is diverging — accruing design debt — and it will read as "good progress, lots of activity" right up until the budget is spent and the surface is still open. The commit log already holds the evidence that tells the two apart. Nobody reads it for that.
Geometric Driven Development starts from one belief: the iteration's inner monologue is already being written, and discarding it is the waste. GDD is not a ceremony added on top of your team. It is a hook that reads the commit log your team already produces and extracts the one number a check-signer has never been able to get without convening a person — a convergence ratio. This post is the proof of its own claim. It was written using GDD, one commit per iteration, and the commit history that produced it is the inner monologue it describes.
The iteration's inner monologue is already being written — your team writes one every commit. GDD is the decision to stop throwing it away. Once the commit log is the monologue, "is this converging?" stops being a judgment call made in a status meeting and becomes a ratio a hook computes for free. It is the same move a processor makes to catch drift as a cache miss in nanoseconds — run sixty million times slower, at the scale of a spec under development.
What follows is that claim, walked. The rest of this post was written the way it describes: each section landed as its own commit, each commit carried a Story trailer that says what the section did, and the convergence toward a finished, graded post was tracked in the same loop the post is about. You are not reading an essay about a method. You are reading the method's output, with the method still running — and at the points where it matters, the method's own inner monologue is printed in the margin, in the monospace strips, so you can check the prose against what its commit claimed it would do.
A
Loading...
🧭A — What GDD is: the commit is the iteration
Geometric Driven Development treats one artifact you already produce as the load-bearing one: the commit message. Not the diff — the message. The diff says what bytes changed. The message says what an iteration decided, and a well-written one says why. GDD's first move is to stop treating that sentence as exhaust and start treating it as the iteration's inner monologue.
It works because of a discipline this repository already runs under: one iteration equals one commit. An iteration is any substantive round — a new section, a renumbering pass, a folded-in source, a reframe. When you commit each one separately, each commit message becomes a true entry in a narrative. Bundle three iterations into one commit and the message can only describe the heap; it cannot narrate the decisions, because three decisions do not have one voice.
The loop in the diagram above is the whole method. A commit lands with a Story: trailer — a paragraph of plain prose stating what this iteration did and why. A post-commit hook reads the trailer and appends it to a per-spec file: the monologue. The same hook counts what the iteration opened and closed against the spec's design surface and updates a number: the convergence ratio. A second script reads the monologue and the number and writes the next move. Then the next commit. Nothing in that loop is a meeting, a status doc, or a human reading a hundred commits to guess a trend. Every link is a hook firing, a file appended, an integer recomputed.
For you, the person who funds the spec, the consequence is direct: the narration your engineers already write becomes a record you can actually query — not "what changed" but "what was being reasoned about, iteration over iteration." The monologue strip below is this section's own entry in that record. Iteration 1 of this post brought the file into existence and registered it into the loop; here is what its commit said it did.
monologue · commit fe791163 · iteration 1
Story: Iteration 1 brings the post into existence as a GDD-tracked artifact — the mutual instantiation made concrete before the body is written. The post file is created with its permanent opening; then the registration — the post's path joins the tracked-artifact registry, and the GDD hooks widen to match it. From the next commit on, this post's own commits are captured into its monologue. The post writes itself into the loop it describes.
🧭 A → B ⚖️
B
Loading...
⚖️B — The trap: converging and diverging look identical from a meeting
Here is the claim, stated so you can attack it from your own experience: from a status meeting, a converging spec and a diverging spec are physically indistinguishable. Both show activity. Both show new sections. Both show an engineer who can talk fluently about progress. The difference between them is invisible at the altitude a meeting operates at — and it is the only difference that decides whether your money produced a finished thing or funded an expanding surface.
A spec has a design surface: the set of open questions it has not yet resolved. Every iteration does one of two things to that surface. It retires a question — adds the section that answers it, removes the open item — or it opens one — surfaces something new the expansion just exposed. A healthy spec retires faster than it opens; the surface shrinks toward empty, which is what "done" means. A diverging spec opens faster than it retires; the surface grows, and the spec is further from done after the iteration than before it, while reading as "good progress" the entire way down.
The book this work comes out of names the person this matters most to, and the equation they are already running without the vocabulary for it.
Somewhere in your organisation there is a person who signs the largest checks. [...] The check writer will sign when Rc becomes measurable. That is the only thing that will cause them to sign. Not a lawyer's opinion. Not a governance framework. Not a compliance audit. A number that lives outside the system being overseen.
That chapter is about insuring deployed AI, where the unmeasured quantity is role continuity. But the shape is general. The check-writer of a software project is you, and the quantity you cannot currently measure is convergence. You sign the next quarter's budget on a status meeting — a lawyer's-opinion-grade input. GDD is the move that produces the other kind of input: a number that lives outside the meeting, computed from the log, that the engineer presenting cannot round up.
Sit with what that means backward, not only forward. Every spec your organization has ever funded generated this signal — commit by commit — and discarded it commit by commit. The log was always there. The ratio was always computable. The status meeting was always the weaker instrument standing in front of the stronger one, doing the stronger one's job and doing it worse. GDD is not a new power handed to you. It is one you have been paying your engineers to generate and then instructing the process to throw away.
🧭⚖️ B → C ⚡
C
Loading...
⚡C — The same physics: GDD is the PMU loop, slowed down
GDD did not invent its loop. It borrowed it from a hardware spec being developed in this same repository — the PMU Counter Module — and ran it at a different scale.
That spec describes a closed-loop control circuit on the processor. A performance-monitoring counter is the sensor; the cache controller is the controller; cache eviction is the actuator. Semantic identity is laid out in memory at a strict stride, so that related coordinates sit on adjacent cache lines by construction. When a computation drifts — when it walks to a coordinate it has no business at — the walk crosses a cache-line boundary, the read misses, and the miss is the drift. Not a software inference about drift. The miss is the physical event, measured by the counter, at a canonical threshold the spec calls kE = 0.003 — roughly a third of a percent of signal lost per boundary crossing, the Planck length of drift. Drift stops being a story someone tells after the incident and becomes a number the substrate emits while the work runs.
The PMU spec's measurement is a pre/post-commit delta. The pre-commit hook snapshots the counters for the coordinates a staged diff touches — call it S₀. The commit lands; the tree mutates. The post-commit hook snapshots the same coordinates again — S₁. The delta, S₁ minus S₀, scoped to exactly what the commit changed, is the drift the commit itself caused. Single-sided measurement loses the baseline; the commit's own change has to be the comparator.
GDD is that loop, transposed. The commit is the iteration. The monologue is the drift log. The convergence ratio is the kE-equivalent threshold — the line that separates a spec settling into its basin from a spec scattering out of it. The PMU runs its loop in roughly five nanoseconds of silicon; GDD runs its loop in the seconds between two commits, sixty million times slower, and the geometry is identical.
Why that identity matters to the person signing the check, and not only to the person taping out silicon: it means convergence ratio is not a metaphor reaching for physics to borrow some rigor. When an engineer tells you a metric is like a hardware signal, you are right to discount it — the resemblance is doing the persuading. This is not a resemblance. It is the PMU loop's own geometry — sensor, comparison against a threshold, recorded miss — run in software, against the same class of drift, and you can settle its silicon twin cell by cell today in the 12×12 simulator. The number you would fund a spec against is the same measurement the hardware makes; the clock speed is the only thing that changed. The longer argument for why drift has to be caught at the substrate rather than inferred above it runs in Theta Is Empty. Targets Fill It.
🧭⚖️⚡ C → D ✅
D
Loading...
✅D — Connection: you are already doing the unmeasured versionsix needs · n=1/6
Nothing about GDD asks your team to start writing something they do not already write. Every team writes commit messages. Every project review is already an attempt — an unaided, lossy, human-memory attempt — to answer "is this converging?" You are not outside this loop. You are running it now, with the worst possible instrument: a person reconstructing a trend from a meeting.
The book's check-writer is in the same position with deployed AI:
Every enterprise currently deploying AI is carrying liability that no one has priced. The liability is silent because the signal that would price it does not yet exist.
Swap "liability" for "divergence" and the sentence is about your spec. The divergence is silent because the signal that would price it — the convergence ratio — is being thrown away every commit. GDD does not create the signal from nothing. It stops discarding one you are already paying to generate. That is the connection: this is not a new burden, it is a recovered asset.
🧭⚖️⚡✅ D → E 🤝
E
Loading...
🤝E — Contribution: what you give, what you getsix needs · n=2/6
The exchange is short and worth stating as an exchange, because the price is real and so is the receipt.
You give: commit discipline. One iteration, one commit — no bundling. A Story: trailer on each commit that honestly states what the iteration did and why. A maintained list of the spec's open questions, so the surface the ratio measures actually reflects the design. That is the whole cost. It is a discipline, not a tool purchase, and a team that already commits is most of the way there.
You get: the monologue and the number. The monologue is an append-only file — one entry per commit, the Story trailers stacked in order — that reconstructs what every iteration decided without anyone re-reading a hundred diffs. The number is the convergence ratio, recomputed on every commit, that says whether the design surface is shrinking or growing. And you get the next-move prompt: a script reads the monologue plus the number and writes the directive for the next iteration, so the loop does not need a human to decide what to do next, only to do it.
The receipt is that the next budget conversation has a different shape. Instead of "the team says it's going well," you have a ratio with a trend, an open-questions count, and a readable narrative of the last five iterations. The engineer is no longer the only witness.
And because the hook is per-repository, the receipt compounds the moment you put it on more than one. One funded spec gives you a ratio. A portfolio of funded specs gives you a column of ratios, sorted worst-first — and the quarterly review stops being a sequence of meetings you sit through, each one an engineer's narrative you cannot independently check, and becomes a column you read in a minute. The spec at 0.15-and-falling is at the top of that column before anyone has booked a room to discuss it.
🧭⚖️⚡✅🤝 E → F 🌱
F
Loading...
🌱F — Growth: the loop repairs itselfsix needs · n=3/6
A method that only measures is half a method. GDD's other half is that the loop is allowed to notice its own friction and fix it. The rule, stated plainly: if an iteration of the pipeline requires manual work that the hooks did not trigger, the next thing you do is fix the pipeline so that manual step never recurs. Manual residue is a defect in the loop, and the loop is the thing under development.
This post is the demonstration. At iteration 1, the post-commit hook captured the monologue correctly — and then left the monologue file uncommitted, as residue a human had to flush by hand with a follow-up commit. That hand-flush is exactly the manual work the rule forbids. So iteration 2 was not a writing iteration at all. It was the loop repairing itself.
monologue · commit 08a25f01 · iteration 2
Story: Iteration 2 is a pipeline iteration, not a writing iteration. Its job is to close the one manual step the loop still had. The post-commit capture wrote the monologue but left it uncommitted — the residue the GDD discipline says to eliminate. So the hook now commits the monologue itself, with a recursion guard that makes the re-fired hook a clean no-op. From iteration 3 on, the flush is automatic and the loop is closed end-to-end.
For you, growth is the property that the cost of GDD falls over time instead of rising. A measurement regime that needs constant hand-holding is a tax. One that promotes every manual step into a hook the iteration it appears gets cheaper to run each cycle — and the convergence ratio it produces gets more trustworthy, because fewer of its inputs depend on a human remembering to do something.
🧭⚖️⚡✅🤝🌱 F → G 🔍
G
Loading...
🔍G — Uncertainty: a label for the state you could not see beforesix needs · n=4/6
The convergence ratio resolves to one of four labels, and the labels are the point — they name a distinction your status meeting could not draw.
Converging — the ratio is above one half; the design surface is shrinking faster than it grows; the spec is settling toward done. Plateau — the ratio sits between roughly a fifth and a half; the surface is stable, neither closing nor exploding; acceptable during a deliberate expansion phase, a warning if it persists. Diverging — the ratio is below a fifth; the spec is opening questions far faster than it closes them; the surface is running away. Idle — no activity against the surface at all; the spec is dormant, which is fine if intended and a problem if not.
The honest example is the spec GDD was first built around. The PMU Counter Module sits at a ratio near 0.41 — plateau. That is not a hidden failure; it is a spec in a known expansive phase, adding sections deliberately, with the next iterations targeted at retiring open questions to push the ratio back above one half. The value of the label is that "plateau, expansive phase, by intent" is a sentence you can now say with a number behind it — instead of discovering, two months on, that the expansive phase never ended.
🧭⚖️⚡✅🤝🌱🔍 G → H 🎯
H
Loading...
🎯H — Certainty: why the number is geometric, not just a countsix needs · n=5/6
The convergence ratio is open questions retired divided by open questions added, measured over the last five iterations. The word that matters is ratio — and the reason GDD calls the method geometric rather than merely counted.
A raw count of activity grows without bound and tells you nothing; a thousand commits is not a thousand units of progress. The ratio is taken over a closed, finite set — the spec's open-questions surface — that the method constrains by construction. Each iteration moves that set in exactly one direction per question: retire, or open. The ratio is the rate at which the bounded set is being driven toward empty. "Done" is the asymptote: the surface goes to zero, the ratio's denominator stops growing, and further iterations add no new questions to resolve. That is a geometric statement about a shape contracting to a point, not a tally.
This is also why the number resists being rounded up in a meeting. Every input to it is at the logic layer, not the semantic layer. Whether a commit happened is a fact in the git database. Whether the monologue gained an entry is a file that did or did not change. Whether a question was retired is a line that left the open-questions section. The ratio is integer arithmetic over those facts. There is no step where someone's judgment, optimism, or memory enters — which is precisely the property that makes it the input a check-writer has been missing. It is the same reason the PMU spec puts its comparison in non-Turing-complete combinational logic rather than in software: a measurement that shares a substrate with the thing it measures can drift with it. A measurement at a strictly lower layer cannot.
🧭⚖️⚡✅🤝🌱🔍🎯 H → I 🏛️
I
Loading...
🏛️I — Significance: the discipline of knowing a spec is donesix needs · n=6/6
The significance of GDD is not the file it produces. It is a capability the funder of any multi-iteration effort has never reliably had: the ability to know, from outside the work, whether the work is converging.
That capability has a terminal state the method names Coherence Lock. A spec reaches it when the convergence ratio holds above one half across a defined window and no new open questions land for that window. Past that point the spec is done in the strict sense — not "the team feels good about it" but "further verification adds no information," because the surface it would verify against is empty and stable. Coherence Lock is the spec-scale version of the PMU spec's zero-error condition: a state the loop can certify, not a vibe the room agrees on.
For you, the consequence is that "done" stops being a negotiation. It becomes a condition the log either meets or does not. You can fund the next quarter against a spec at ratio 0.7-and-rising with a clear conscience, and you can decline to fund one at 0.15-and-falling without needing to win an argument about it — because the number, and the monologue behind the number, made the case before the meeting started.
Name the magnitude plainly, because it is the whole return on the discipline. Today, the mechanism that detects a diverging spec is budget exhaustion: you learn the design surface never closed because the money budgeted to close it is already spent. That is a detection latency measured in quarters, and its cost is the quarter. The convergence ratio moves detection to the commit that caused the divergence — a latency of one iteration. GDD does not make a doomed spec succeed; no measurement does. It does the thing a check-writer values more than a save: it tells you a spec is diverging while there is still budget left to kill it, redirect it, or fund the iteration that closes the surface. The return is not a better metric. It is the difference between an autopsy and a diagnosis.
🧭⚖️⚡✅🤝🌱🔍🎯🏛️ I → J 🔁
J
Loading...
🔁J — The proof: this post is a GDD-tracked artifact
Everything above would be a description of a method. This section is the part where the description and the thing described are the same object.
This post is registered into the GDD loop exactly the way the PMU spec is. It has a tracked-artifact entry; its commits fire the same hooks; its Story trailers are captured into its own monologue file. The two monologue strips you have already read are not illustrations — they are live entries from this post's monologue, the actual commit messages that produced the sections they sit in. When this post claims a method, the claim is checkable against the commit that made the claim, because the commit and the claim shipped together.
You are reading the output of the loop, with the loop still visible. This post was not written and then explained. It was iterated — each section a commit, each commit a Story trailer, the trailers captured into a monologue, the monologue read back to choose the next iteration. The method did not get described into existence. It got committed into existence, and the log above is the receipt. If the prose in any section does not do what its monologue strip said the iteration would do, that is a measurable defect — and GDD is the discipline that would catch it.
The mutual instantiation is the entire argument compressed: a method whose first honest test is whether it can build the document that explains it. It passed that test in public, in this repository, in the commits above.
🧭⚖️⚡✅🤝🌱🔍🎯🏛️🔁 J → K 🧪
K
Loading...
🧪K — What has to be true for the number to mean anything
A convergence ratio is only as honest as its inputs, and an honest post states the inputs out loud rather than letting the reader discover them later. GDD's number is real only if three assumptions hold.
Commits are deliberate. One iteration, one commit. If your team bundles a week of work into a Friday commit, the monologue has one entry for five decisions and the ratio is measured against a fiction. GDD requires the iteration discipline first; the measurement is a consequence of it, not a substitute for it.
The Story trailer is honest. The trailer must state what the iteration actually did. If a trailer claims a question was resolved that was not, the monologue records a convergence the spec did not earn. GDD measures the log; it cannot detect a log that lies. This is why the method pairs the ratio with the readable monologue — a human spot-checking the narrative against the diffs is the backstop the integer arithmetic cannot provide.
The open-questions surface is maintained. The ratio is taken over the spec's list of unresolved questions. If that list is not kept current — if resolved questions are not struck and newly exposed ones are not added — the denominator drifts from reality and the ratio measures bookkeeping instead of design. The surface is the spec's responsibility; GDD measures it, it does not author it.
Two more assumptions sit under the impact — as distinct from the number — and a check-writer should price them before acting on this post. The first: divergence is common enough in your specs to be worth instrumenting. If your multi-iteration efforts reliably converge on their own, GDD measures a problem you do not have — though the honest counter-evidence is in plain sight, since the PMU spec this method was built around sits at plateau, ratio 0.41, mid-expansion, and a spec that runs long enough to need a funding decision is exactly the spec that drifts. The second: you can require the discipline. GDD's return reaches you only if one-iteration-per-commit and an honest Story trailer become non-optional for the teams you fund — a mandate, not a tool install, and the one part of this that the check-writer, specifically, is positioned to make stick.
Hold the first three assumptions and the number is load-bearing: a genuine measurement of convergence an engineer cannot inflate. Hold the last two and that number reaches you as changed practice rather than as a dashboard nobody acts on. Break any of the five and GDD degrades gracefully — toward a monologue still more readable than a hundred raw commits, and a ratio you should not yet trust. The method does not claim to manufacture rigor. It claims to measure rigor the iteration discipline already produced, to price the assumptions that measurement rests on, and to stop you from discarding either.
🧭⚖️⚡✅🤝🌱🔍🎯🏛️🔁🧪 K → L 🚪
L
Loading...
🚪L — The route
You can run the first half of GDD this week, without adopting anything. The next time a spec or a feature is under development, require one iteration per commit and a one-paragraph Story: trailer that says what the iteration decided. That alone converts your commit log from exhaust into a readable monologue. The hook that turns the monologue into a ratio is the second half — forty lines of script, not a platform — and it ships in the open as thetacog-mcp, the npm package this repository's GDD loop runs on.
The route through the rest of this work runs through one address: /rooms. The convergence ratio, the PMU counter spec it borrows its physics from, the post-commit XOR gate that this loop is built on, and the actuarial argument in The River Is the Prompt are the ground the rooms run on. Everything branches off from there at the right coordinate.
Your commit log has been writing the story of every spec you fund — one true sentence per iteration, narrating toward done or away from it — and the process you run has been instructing itself to discard that sentence the moment it arrives. GDD is the one-line amendment to the instruction: keep the sentence, stack the sentences, read the number they make. The log is the witness. The ratio is the verdict. This post is the precedent — written under the method, graded under the method against the reader who signs the check, and filed with its own commit history as the evidence that the method holds.
🧭⚖️⚡✅🤝🌱🔍🎯🏛️🔁🧪🚪 L → /rooms 🎯
Research and lineage. The "start from why" framing is Simon Sinek's. The post-commit hook this loop is built on was first walked in The Post-Commit XOR Gate; the substrate physics it borrows — drift caught as a hardware cache miss — is the subject of Theta Is Empty. Targets Fill It. and the actuarial stakes are walked in The River Is the Prompt and the Budget Moves On. The framing of the goal-prompt and the commit log as one document is walked in The Goal Prompt and the Commit Log Are One Document. The book passages are from Tesseract Physics, Chapter 12, "The Budget Is the Proof"; the kE = 0.003 drift constant is derived in Chapter 0, "The Razor's Edge". The hardware comparison can be run interactively in the 12×12 PMU simulator. The convergence ratio is computed over a closed set of open questions — a finite design surface — which is what makes the metric geometric rather than a count of activity. GDD's loop runs in the open in this repository: the monologue file is append-only, the metric is plain JSON, every link in the chain is a hook firing rather than a convention being remembered.
