uscha.dev
the underlying thesis

Specs are the source code. Code is a build artifact.

Why closing the cycle with reverse discovery doesn't add a command — it inverts what the asset of a software system is.

the specs are the source code
the LLM is the compiler
reverse discovery is the decompiler — an ordinary decompiler recovers only structure; this one also recovers intent, the why

01 · Before — the code is the truth

This is how almost every project works today: the asset is the code. The spec — if it exists — is documentation: written once, rotting in silence, because nothing forces it to move when the code moves. Six months in, nobody believes it, and rightly so. When the document and the code disagree, the code wins. Always.

intent in someone's head written once SPEC documentation rots in silence — nobody believes it, rightly implemented CODE the asset · the only truth in any conflict, it wins
The flow is one-way, and the stroke tells the story: the code is the solid box — the asset. The spec is dashed — dispensable, and decomposing from day one. A 25-year-old legacy system is this same drawing with the spec already gone.

Note the economic consequence: everything the organization knows about the system lives in an artifact that can only be read by executing it. When the one person who understands it retires, the knowledge retires too.

02 · The analogy — nobody edits the binary

Think of C. Nobody hand-patches the compiled binary — it would be madness: you edit the .c and recompile. The binary is disposable, regenerable; the .c is the asset. The thesis says: with good enough LLMs, source code moves into the binary's seat. You edit the spec and "recompile": the LLM generates the code.

A compiler alone, however, goes in one direction. While the methodology was forward-only (intent → spec → code), the spec was one more input — not the canonical representation — because the world is full of systems where only the code exists. The return trip was missing.

03 · After — the closed cycle inverts the asset

Reverse discovery adds the inverse direction: code → spec. It is the decompiler. And with both directions, any system — even the legacy with not a single document — can enter the canonical format. With one condition that does all the work: legacy code mixes intent with accident. Bugs customers already depend on, timeouts nobody decided. A naive decompiler photocopies the bugs as features. That is why the one step no automatic tool can perform is a human gate: the machine extracts evidenced candidates, and only a person rules on what was intent (preserve), what was a bug (fix), and what nobody ever decided (undefined).

SPEC PACKAGE + BEHAVIOR LEDGER the canonical asset CODE build artifact regenerable forward · the LLM compiles reverse discovery decompiles intent only what is judged gets promoted CURATION human verdict preserve·fix·undefined legacy system = 100% drift the asset appreciates with every model generation; the code is regenerated and depreciates — like a binary
The strokes have flipped: now the solid box — the asset — is the spec package plus the behavior ledger, and the code moved to a dashed line: disposable, regenerable. Every return path passes mandatorily through curation: no human verdict, no promotion — the gate is measured by the engine, not promised by prose.
Without curation in the middle, reverse discovery doesn't recover intent — it produces a tidier photocopy of the legacy, with the bugs fossilized as features.

04 · Corollaries — what follows on its own

The asset appreciates; the code depreciates. If the code is regenerable, every model improvement upgrades the "build" for free: the same spec package, recompiled with the 2027 LLM, produces better code. Specs are the only investment that doesn't age — and that is the commercial argument: you don't sell the rewrite, you sell the asset that also survives the next rewrite.

Fidelity becomes measurable. If you decompile what you compiled and the result matches what you had, the methodology is lossless — and that is a number, like the bootstrap test of a compiler that compiles itself:

specs forward code discovery specs′ ≈ specs? measured by ID coverage (uscha-spec) and, since 1.90, by static + behaviour recoverability (0.815, bounded) — see the truth-pass table
The methodology's self-test: discovery(forward(specs)) ≈ specs. Nobody in the spec-driven space measures the fidelity of their own methodology; this cycle turns it into a publishable number.

Drift and migration are the same problem. A spec three weeks behind its code is 5% drift; a legacy with no document at all is 100% drift. The same question at different scales — with the honesty that today they are different instruments, not a shared engine.

05 · Truth-pass — what is real today, what is still vision

The pitch is beautiful, and precisely for that reason it deserves distrust. The house rule: under-claim, then wire, then re-claim. State as of today (kit 1.90.0):

ClaimStatusWhere
Curation with verdicts, measured gate, append-only auditable ledger REAL1.64.0 · ADR-009/010
Oracle distinguishing preserved behavior from declared fixes REAL1.65.0 · golden-diff
Round-trip by ID coverage (which specs are traceable in the code?) REAL1.65.0 · roundtrip, advisory
Semantic round-trip (does the code say the same thing as the spec?) REAL (measured, bounded)recoverability 0.815 measured, behaviour measured in 12/12 — anchors names and behaviour · 1.90 · ADR-030 (amended)
Implementation replaceability, demonstrated on bounded systems — independent compilations regenerate the same system from the canonical package, a withheld oracle certifies it — four blind compilers across two vendors (Haiku · Sonnet · Opus · OpenAI Codex gpt-5.5) — one model of the second vendor, so the arm is a falsification test, not a survey REALDiamond Bench: 12 archetypes (11 Python + 1 JavaScript, one multi-unit): 8 PASS, 4 PARTIAL (measured September 2026) · 1.74–1.99 · ADR-017/018/020/025/028/029/042
Per-compiler fidelity (reverse discovery over each compiled artifact) + human curation of machine-generated code, one verdict per observation REAL1.79–1.80 · ADR-022/023 · UNMEASURED stays literal where no verdict exists
Controlled authoring (EARS+STE) reduces inter-compiler variance REAL (measured, behaviour-first: dense archetypes helped, simple ones null/harm; structural variance alone no longer carries a claim — ADR-027)deconfounded across 5 archetypes: REDUCED in 1 (guard −61%, NOISY 0.642), IMPROVED in 1 (scheduler, +1 oracle-green), two nulls, one WORSE · 1.76–1.84 · ADR-019/021/024/025/026/027
"The code is fully regenerable from the specs" (arbitrary systems) VISIONthe bounded half is REAL (row above): the bench ran on 12 archetypes, 8 regenerate to the same system under a withheld oracle, 4 PARTIAL. What stays VISION is the word totally and the words arbitrary systems — generalization past bounded archetypes is the open frontier M5 exists to answer, and no run has answered it yet (ADR-018)
"Drift = incremental reverse discovery, same engine" REJECTEDvalid idea, rejected as architecture · ADR-011

And note the elegant part: the piece of the diamond that is already real — the formal, traceable, blocking human-judgment layer — is exactly the one no tool in the space has. The part that remains vision is the one anyone could promise. The hard part is built and the glamorous part is missing: the right order.

06 · Why "diamond"

Because it isn't the feature. Reverse discovery — the command — is only the first materialization. What the closed cycle changes is the category of the whole project: from development methodology to canonical representation format for systems. Code comes and goes; the decisions — evidenced, judged, recorded — are the only thing worth migrating.

State verified against kit 1.96.0 · sources: ADR-009, ADR-010, ADR-011, ADR-016–ADR-030, CHANGELOG-1.64.0, CHANGELOG-1.65.0, CHANGELOG-1.72.0–1.96.0 · the REAL/VISION/REJECTED labels follow the repo's INV-TRUTH-01 rule.

07 · The program, measured — T0 → 1.96.0

The Diamond program ran as eight releases of the kit measuring itself. Every number below comes from a committed, regenerable report in the repo — none is narrated:

InstrumentMeasured resultReleases
Diamond Bench — 12 bounded archetypes × 4 blind compilers across two vendors (Haiku · Sonnet · Opus · OpenAI Codex gpt-5.5), each judged by a withheld oracle 8 PASS · 4 PARTIAL (measured September 2026). The oracle also caught a convergent aliasing bug two independent compilers shared — a defect no code review of either would have flagged as suspicious. 1.74–1.99
Controlled language, deconfounded — free prose vs EARS+STE, same generation, shared oracle, 5 archetypes REDUCED in 1, IMPROVED in 1: the decision-dense guard dropped variance −61%; the control and the state-machine read null; the transformer read WORSE — the rewrite sharpened a latent ambiguity ("exactly the fields") into a commitment the oracle rejects; the second decision-dense archetype (scheduler) gained an oracle-green and raised mean pass-rate while variance rose — two compilers had converged on the same bug in free prose. 1.76–1.83
Intra-model variance, the noise floor — bench-r2 over 10 archetypes × 4 models × 2 runs NOISY: same-model reruns differ structurally about as much as different models do (mean intra/inter 0.82), while behaviour stays stable on 36 of 40 reruns. Adding the second vendor moved two entries out of NOISE — it widened the inter-compiler spread more than the intra floor. Every variance claim the program makes now carries a per-entry SIGNAL/NOISY/NOISE qualifier, and the controlled-language reading above is behaviour-first. 1.84
First non-Python archetype — a JavaScript token-bucket rate limiter, 4 blind compilers under a withheld oracle PASS 25/25 × 4, distinct implementations, static surface (module exports listed by Node) 3/6/3 and 8 — the replaceability claim holds outside Python; a JS entry with no node on PATH reads PENDING/UNMEASURED, never a fake pass. 1.85
First multi-unit archetype — ledger-lite: two modules joined by a seam ADR, compile/0.1 exercised over 2 source units, 4 blind compilers under a withheld oracle The bench's first IR with real edges (3, extracted from the seam decision): PASS 24/24 × 4, entry unit routed through the CLI over both units, static surface main+post — the seam holds under 4 independent compilers, across two vendors; the wrong/ that breaks the seam (balance logic moved into the CLI) and the one that ignores the model unit entirely both read red. 1.85
Round-trip recoverability — how much of the pinned IR the mechanical reverse organs anchor, over 12 archetypes × 4 compilers each Mean recoverability 0.815, measured — the reverse organs anchor names and behaviour; the manifest footing would read 1.000 and is excluded as tautological (it is what the compiler CLAIMED, not what was recovered). It read 0.062 with the behaviour dimension UNMEASURED in 12/12 until the 12 oracles were curated with per-case AC tags (1.90, ADR-030 amended): a named absence, not a zero, and what moved the number was the tagging — payloads and expectations untouched. The diamond's reverse half is a measurement with a stated ceiling, not a promise. 1.90
Cross-vendor arm — the same 12 archetypes compiled blind by a SECOND vendor (OpenAI Codex, gpt-5.5 via codex-cli), same canonical packages, same withheld oracles (ADR-042) The arm validates on all 12 and beats the Claude arms on two entries (rest-handler 15/15, scheduler 30/30). It loses exactly one case, on transformer, and that case is the finding: it read “an object with exactly the fields first/last/age” as forbidding an extra field, declared that reading in its unresolved_intent before the oracle judged it, and reproduced it in a second independent run. Three Claude models had converged on the other reading, so the ambiguity was invisible while every compiler came from one vendor — the same latent ambiguity the controlled-language row above surfaced from the other direction. The entry moved PASS → PARTIAL. What stays UNMEASURED: one model of that vendor, n=2 runs, two vendors of many. 1.99
Fidelity per compiler — the M1 static extractor applied to each compiled artifact Behaviourally near-identical compilers expose visibly different surfaces: 19–21/23 on the same oracle through 4, 5, 8 and 13 public functions. 1.79
Curation of machine-generated code — one human verdict per observation, append-only, fail-closed store Closure is measured where a human judged and stays the literal UNMEASURED where none did — absence named, never faked. 1.80
The method on itself — releases shipped through a blind review before release (independent in most; two, 1.74.0 and 1.75.0, were inline self-reviews and say so in their changelogs) The reviews caught real defects in most releases — each catch is recorded in that release's changelog. An earlier per-release tally published here had no ledger behind the exact count and was withdrawn by the 1.85.0 review; this is what the repo can actually show. 1.73–1.81

Provenance limit: the three Claude arms were compiled by hand and recorded the model alias, not the exact resolved model id. A script to record it exists (ADR-050) but no live round has been run, so that gap is still open.

The emerging hypothesis — stated as hypothesis, not conclusion: controlled authoring pays where the prose had slack, and does nothing or harms where it had none. The instrument to test it further is already in the repo.