A software project keeps three documents about itself. The plan: what we are going to do. The log: what we did. The review: how it went. Three documents, written by three different processes, at three different times, and reconciled against each other never.
You pay for all three. You pay for the plan in a kickoff. You pay for the log on every commit. You pay for the review in a meeting that exists, mostly, to perform the reconciliation the three documents never underwent on their own. The gap that meeting is convened to close — between what was planned, what was done, and how it went — is the exact place a budget goes to die, because no single document is responsible for it.
Geometric Driven Development makes a claim that sounds like a trick and is not. Those are not three documents. They are one document, read in different directions. The goal prompt is the document read forward — what to do next. The commit log is the same document read backward — what was done. The grade is the measured distance between the two readings. When the distance is zero, the plan and the log say the same thing, and that is the only rigorous definition of "done" anyone has been able to write down.
This is the second post written under GDD, and it exists to publish the thing the first one used and never showed: the goal prompt itself. The first post — Your Commit Log Is a Convergence Signal — explained the loop. This one prints the prompt that drove the loop, sets it beside the commit log it produced, and lets you measure the distance yourself. The post about the prompt contains the prompt. The claim and its evidence ship in the same file — which is, exactly, the claim.
The plan, the log, and the review are one document — and the budget meeting exists to hand-reconcile what the document should reconcile by itself. GDD's goal prompt is that document read forward; the commit log is it read backward; the convergence grade is the distance between the two readings. Zero distance is done. Every other definition of "done" is a negotiation — and you are the one who pays for the negotiation.
What follows is that claim, walked — and, where the first post explained, this one exhibits. The actual /goal prompt is printed in full below, set beside the commit log it produced and positioned against the practices you already use, so the distance between intention and result is something you measure rather than something you take on trust.
A
Loading...
📑A — Three documents, reconciled never
The plan, the log, and the review do not disagree because anyone is careless. They disagree because they are structurally separate — three files, three authors, three moments — and nothing in the process is responsible for the space between them. The space is not on anyone's desk. So it grows.
The book this work comes from has a name for what that separation costs, and it is not a metaphor:
An Org Chart is a normalized database. It separates people by title, department, and function. To accomplish a complex project, you run a JOIN operation — ask your boss, who asks another boss, who asks a project manager, who asks a dev. That's n hops. Each hop costs epsilon. [...] The definitive slide deck defining the R&D project's capabilities. The organization adopted those slides for their own meetings — the only artifact in the building actually touching the metal.
Three documents is the same JOIN. The budget meeting is the hops — boss to manager to dev and back — run by hand, in a room, once a quarter, to compute a number the three documents could have agreed on continuously and did not. What the chapter found in a Fortune 500 R&D org is what your project does to itself every review cycle: the reconciliation is real work, it is expensive, and it is being done by the most expensive instrument available — a room full of paid attention — because no document was made responsible for it.
For you, the person funding the project, this is where the money is quietly going. Not into the plan, not into the log — into the unowned space between them, and into the recurring meeting convened to survey that space and report back a guess.
📑 A → B ⚖️
B
Loading...
⚖️B — GDD reads two ways, and both are true
The acronym is deliberate, because the method is two claims that turn out to be one.
Read it as Goal-Driven Development and it describes a control loop: a goal engine states what the next iteration should achieve, the iteration runs, the engine grades the result against an ideal reader, and the grade decides the next goal. That is the loop the first post walked — commit → Story trailer → monologue → metric → goal-prompt → next commit.
Read it as Geometric Driven Development and it describes a shape. The goal prompt and the commit log are not two artifacts that a process compares. They are one document with two ends. The prompt is the document read forward — what to do. The log is the document read backward — what was done. The convergence grade is the literal distance between the two readings, and the spec is finished exactly when that distance reaches zero: the plan and the log have become the same text, and there is nothing left to reconcile because there are no longer two things to be a gap between.
Both readings are true at once, and that is the point. The goal engine grades; the geometry is what the grade measures. For you, the consequence is concrete: you stop maintaining three documents and paying a meeting to reconcile them, and you start maintaining one document and reading it twice. The reconciliation is not performed. It is measured — and a measurement is cheaper than a meeting, and it does not round itself up.
📑⚖️ B → C ⚡
C
Loading...
⚡C — What "geometric" actually means
The word geometric is not decoration, and it is not borrowed from CAD software. It is defined in the book, precisely, as an axiom — and the axiom is what the methodology is named after.
The system no longer runs an operation and then runs a check. The strike is the report. [...] Standard architectures keep operation and audit as separate factors. The system performs the operation. Some other mechanism — a filter, a check, a regulator — reads the result and verifies. The two are multiplicatively independent. Most failures live in the gap between them, where the operation drifts and the audit remains static.
That is the three-document problem, stated as physics. The plan is the operation read forward; the review is the audit; and they are multiplicatively independent — separate factors — so the failure lives in the gap, where the work drifts while the review sits static until the quarter forces them into one room.
The axiom removes the gap by construction. When the document's two readings are the same document, the audit cannot stay static while the operation drifts, because — in the chapter's exact words — "the audit is the operation's geometric form. There is nothing for the audit to be independent of." GDD is that axiom applied one level up from silicon, at the scale of a spec under development. The goal prompt and the commit log are not an operation and a separate audit of it. They are one geometric object, and the convergence grade is its measured deformation. Geometric names the move that makes the audit impossible to decouple from the work — because the strike is the report.
📑⚖️⚡ C → D ✅
D
Loading...
✅D — Connection: you already keep all threesix needs · n=1/6
You are not missing any of the inputs GDD needs. Every project you fund already has a plan — a kickoff doc, a spec, a roadmap. Every project already has a log — the commit history, whether or not anyone reads it. Every project already has a review — the meeting on the calendar. You are already paying for all three documents and for the reconciliation between them.
GDD adds nothing to that list. It removes two of the documents by making them readings of the third. The plan stops being a separate file that ossifies the day it is approved; it becomes the goal prompt, regenerated each iteration. The review stops being a quarterly event; it becomes a grade recomputed each commit. What remains is one document — the iteration record — and two ways of reading it.
The connection is that this is not a new practice to adopt against resistance. It is the practice you are already running, with the expensive parts — the parallel documents, the reconciliation meeting — taken out.
📑⚖️⚡✅ D → E 🤝
E
Loading...
🤝E — Contribution: here is the promptsix needs · n=2/6
A post that claims the goal prompt is half the document owes you the goal prompt. Here is the actual /goal directive that produced the post you are reading — copied verbatim, nothing withheld:
# /goal — GDD post #2: "The Goal Prompt and the Commit Log Are One Document"
Write and publish a second GDD blog post, using GDD. The first post ("Your Commit Log Is a Convergence Signal", 2026-05-19, 10 iterations, shipped at 95% triple-median) explained the loop. This post publishes the /goal prompt that drove it and closes the claim the first post left implicit.
## The claim to land
"GDD" reads two ways, both true. GOALS-driven: a goal engine grades each iteration against an ideal reader. GEOMETRIC: the commit-log inner monologue and the goal engine's grading criteria are one document read in two directions — the log says what was done, the grade says how far from done — and a spec converges exactly when the two coincide at every coordinate. That coincidence IS the geometry; the convergence ratio is the distance between the two documents; zero distance is Coherence Lock. GDD is defined in the repo — docs/architecture/geometric-driven-development.html, the gdd scripts, the pre/post-commit hooks, the monologue files — not in any prompt. The prompt is a pointer to running code.
## What the post must do
1. Publish the actual /goal prompt as an in-post artifact the reader can copy — the post about the prompt contains the prompt (scripts/gdd/goals/blog-post-gdd.md, and this prompt itself).
2. Show the coincidence with real evidence: quote commit Story trailers from the last few days beside the grades they carried — the first post's iters 1-10 AND the PMU spec's iters 5-11. Both threads converged on one instrument: the post graded predictive/impact/confidence; PMU spec iter 11 added §21, a triple-percentage self-assessment, all groups >= 95%. One grading instrument, two specs — the geometry, observed in the wild.
3. Cite the repo as the definition: goal-prompt.mjs (the METRIC->GOAL aggregator), spec-monologue-update.mjs, the post-commit auto-flush, the convergence-metric fix (now counts the architecture-blocking surface, not all bullets) — all landed in the last three days.
## The method — the goal reads the repo as it iterates
This prompt is intentionally a pointer, not a payload. Do NOT follow it as a frozen directive. Before EACH iteration: run `node scripts/gdd/goal-prompt.mjs <slug> --no-copy`, read `git log --oneline -15` and the monologue-file tail. Let the repo's current convergence state be that iteration's directive. This prompt says only HOW to read the repo; the repo says WHAT to do next. Iteration 1: pick a slug, create src/content/blog/2026-05-19-<slug>.mdx, register it in SPEC_REGISTRY (both gdd scripts) + the hook greps — as the first post's iter 1 did. From iter 2 the post is in the loop and goal-prompt.mjs drives it. One iteration = one commit (HARD per CLAUDE.md). Story trailer carries the iteration narrative; post-commit captures and auto-flushes it. If any step needs manual work the hooks did not trigger, fix the pipeline that same iteration.
## Grading — same gate
Grade each iteration against the Budget Writer ideal reader (memory/feedback_budget-writer-default-persona.md): predictive power %, impact-if-true % (list the assumptions explicitly), confidence %. PUSH when the median of the three reaches 95+. Grades go in the Story trailer — and this post's grades, being the goal engine's own output, ARE the coincidence the post describes.
## Constraints
Canonical blog architecture (A-C framing / D-I six needs / J-L landing), WHY-first opening, MCPHeraldicCrest + breadcrumb per section, one primary CTA (/rooms), no MDX-forbidden chars (validate-mdx blocks), book deep-links verified before each commit, research-citations footer, paradox voice, Casimir grip. Final Story trailer records the three percentages at push time.
Read it once and the strange thing is visible: almost none of it says what to write. It says how to read the repository, how to commit, how to grade, what not to do. The one paragraph headed "The claim to land" is the only payload; everything else is procedure. That is not an oversight. It is the design — and the next section is why.
📑⚖️⚡✅🤝 E → F 🌱
F
Loading...
🌱F — Growth: the prompt is a pointer, not a payloadsix needs · n=3/6
A normal prompt is a payload: it carries the instructions, and the work is to execute them. A payload prompt goes stale the instant the repository moves past the state it assumed — which is to say, after the first commit.
The GDD goal prompt is a pointer. It does not carry the next iteration's instructions; it carries the address where those instructions can be computed. The method section is explicit about it: before each iteration, run node scripts/gdd/goal-prompt.mjs <slug>, read the recent git log, read the tail of the monologue file. The prompt says how to read the repository; the repository's current convergence state says what to do next. The directive is regenerated from HEAD every cycle, so it cannot describe a stale repository — it describes the one that exists at the moment the iteration starts.
This is why the methodology is defined in the repo and not in the prompt. The architecture document, the goal-prompt.mjs aggregator, the monologue-capture hook, the convergence metric — those are GDD. The prompt is a forty-line note that tells an agent where they live and how to consult them. Hand the same prompt to a fresh agent six commits later and it produces the correct next iteration for commit six, not a replay of commit one, because the prompt never contained the iterations — it contained the pointer.
For you, growth means the plan stops being the thing that goes out of date. The plan is no longer a document with a shelf life; it is a function evaluated against the current repository. A plan that recomputes itself from HEAD is a plan you never have to convene a meeting to refresh.
📑⚖️⚡✅🤝🌱 F → G 🔍
G
Loading...
🔍G — Uncertainty: what GDD is notsix needs · n=4/6
A new method is worth nothing if you cannot locate it against the ones you already trust. GDD is not the first practice to take intent, decisions, or convergence seriously. It is the first to put all three in the commit log. The honest map has three regions.
Practices that write intent before code.README-Driven Development (Tom Preston-Werner) writes the README first; Amazon's Working Backwards PR-FAQ writes the launch announcement first; GitHub's Spec Kit makes a specification generate the implementation; TDD and BDD write the failing test first. Each produces a forward artifact and builds toward it — but none reconciles that artifact against what was actually built, and none measures whether the intent itself has stopped moving. They write the plan. They do not close it against the log.
Practices that record decisions separately.Architecture Decision Records (Michael Nygard) preserve one decision per immutable, append-only record; the git-commit-as-documentation tradition (Tim Pope, Chris Beams) insists the commit body explain why. This is GDD's closest neighbor — append-only, one decision per record. But an ADR is a parallel artifact a developer must remember to author, decoupled from the commit that implements it, and the archive is flat: it is read, never measured. GDD makes the decision record be the commit's Story: trailer, so no separate authoring step exists, and then computes a number over the stream that ADRs only archive.
Practices that measure tickets and pipelines. Agile burndown and velocity chart remaining story points toward a sprint goal; Google's DORA metrics measure delivery speed and stability. Both compute convergence — and a velocity chart converging to a flat line is genuine prior art GDD should credit. But they measure work throughput and delivery safety. A burndown can reach zero while the spec is still diverging; a DORA dashboard can be all-green while the blueprint is being rewritten weekly. They measure the conveyor belt. They do not measure whether the blueprint has stopped changing.
None of the nine turns the commit log itself into a convergence metric over the spec's open-question surface. That is the unoccupied coordinate, and it is the one GDD fills.
📑⚖️⚡✅🤝🌱🔍 G → H 🎯
H
Loading...
🎯H — Certainty: the coincidence is observablesix needs · n=5/6
The claim that the prompt and the log are one document would be a metaphor if the coincidence between them could not be observed. It can, and it was — twice, in parallel, in this repository, in the three days before this post was written.
The first post graded itself on three percentages — predictive power, impact-if-true, confidence — against one ideal reader, and shipped when their median crossed 95. While that ran, the PMU counter spec the methodology was built around reached its own iteration 11, and that iteration added a section numbered §21: a triple-percentage self-assessment, every group scored, all at or above 95. Nobody coordinated that. Two specs under the same loop — a blog post and a hardware spec, as different as two artifacts in one repository can be — independently converged on the same grading instrument. That is not a shared style. That is the geometry: when the goal engine's grading criteria and the commit log's inner monologue are one document, two specs reading that document arrive at the same measure of done, because there is only one measure to arrive at.
The grade is the distance between the two readings, and the distance is integer-honest. Whether a commit happened is a fact in git. Whether its Story: trailer claimed an iteration is a line in a file. Whether the grade moved is arithmetic over those lines. There is no point where optimism enters. Zero distance — the prompt's stated goal and the log's recorded result coincide at every coordinate — is the state the first post's section called Coherence Lock: done in the strict sense, because the document read forward and the document read backward have become the same text.
📑⚖️⚡✅🤝🌱🔍🎯 H → I 🏛️
I
Loading...
🏛️I — Significance: done stops being a negotiationsix needs · n=6/6
The book names the person this matters to most, and the single thing that moves them:
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.
For a spec under development, the number that lives outside the system is the distance between the goal prompt and the commit log. While that distance is unmeasured, "done" is whatever the review meeting negotiates it to be — and the negotiation is won by whoever is most fluent, not by whatever is most true. When the distance is measured, "done" stops being negotiable. It is the condition where the document read forward and the document read backward coincide, and that condition is either met in the log or it is not.
That is the significance, stated for the person who signs: GDD does not give you a better meeting. It removes the meeting's job. The reconciliation the quarterly review existed to perform is performed continuously, by a hook, as a number — and a number you did not have to convene anyone to produce is a number nobody can talk you out of.
Name the magnitude in the unit that bills you: frequency. The reconciliation between the plan and the build happens today at the cadence of the review — quarterly, monthly if you are diligent — and that cadence is also the resolution at which you can first see that the plan and the build have diverged. GDD moves the reconciliation to the cadence of the commit. A divergence a quarterly review catches has had a quarter to compound: built on, depended on, shipped around. The same divergence, surveyed every commit, is caught while it is still one iteration wide and still cheap to close. You are not buying a better meeting. You are buying the difference between a quarter of drift and a commit of it.
📑⚖️⚡✅🤝🌱🔍🎯🏛️ I → J 🔁
J
Loading...
🔁J — The proof: the prompt beside its own log
Section E printed the goal prompt — the document read forward. Here is the same post's commit log — the document read backward. Set them beside each other and the distance between the two readings is something you measure, not something this post asks you to believe.
You are holding both ends of one document. The prompt in section E is the forward reading; the log above is the backward reading. The first post proved a method could build the artifact that explains it; this post proves something narrower and sharper — that the instruction and the record can be printed in the same file and shown to coincide. If a line of this post does something the prompt did not ask for, or skips something it did, the distance is not zero and the claim is false. Measure it. The prompt is forty lines up the page.
The first post's commit log climbed a convergence grade from 82 to 95 across ten iterations. This post's log is shorter because the loop was already built — the pipeline it runs on hardened during the first post and needed no repair here. That, too, is in the record: a methodology whose second use costs less than its first is a methodology that is converging.
📑⚖️⚡✅🤝🌱🔍🎯🏛️🔁 J → K 🧪
K
Loading...
🧪K — What has to be true
The coincidence between the prompt and the log is real only if three things hold, and a post that claims a measurement owes you its load-bearing assumptions stated plainly.
The commits are deliberate. One iteration, one commit. Bundle a week of work into one commit and the log has a single entry for five decisions — the backward reading is now lossy, and the distance it reports is fiction.
The Story trailer is honest. The trailer must say what the iteration did. The log is only the document-read-backward if the trailers are true; a trailer that claims a goal it did not meet records a coincidence that did not happen. GDD measures the log — it cannot detect a log that lies, which is why the readable monologue, spot-checked against the diffs by a human, is the backstop the arithmetic cannot supply.
The repo is actually re-read each iteration. The prompt is a pointer; its value is zero if the agent treats it as a payload and skips the goal-prompt.mjs run, the git log read, the monologue tail. Re-reading HEAD is the step that keeps the forward document current. Skip it and you are back to a stale plan — the exact failure GDD exists to remove.
Hold all three and the distance between the prompt and the log is a true measurement of done. Break any one and GDD degrades into what you had before: three documents and a meeting. The method does not manufacture the coincidence. It measures a coincidence the discipline produces, and refuses to let you mistake an unmeasured gap for a closed one.
📑⚖️⚡✅🤝🌱🔍🎯🏛️🔁🧪 K → L 🚪
L
Loading...
🚪L — The route
You can test the claim this week without adopting anything. Take one spec under development. Write its next iteration as a single commit with a one-paragraph Story: trailer. Write the goal for the iteration after it as a pointer — not "do X," but "read the log and the metric, then decide." Do it three times. Then read the prompt forward and the log backward and see whether they have started to converge or whether the distance is still growing. That measurement is GDD, run by hand. The loop that runs it automatically ships as thetacog-mcp — the package whose own description is "Geometric-Driven Development (GDD) toolkit."
The route through the rest of this work runs through one address: /rooms. The goal-prompt aggregator, the convergence metric, the PMU counter spec the geometry comes from, and the first GDD post are the ground the rooms run on. Everything branches off from there at the right coordinate.
Your project keeps three documents about itself. It always has. GDD's claim is that two of them are readings of the first — and that the distance between the readings is the only honest measure of how far you are from done. The prompt is printed above. The log is printed above. The distance is yours to measure.
