Build discipline

Build Discipline

A distilled engineering discipline for building software that keeps working after the demo. It is deliberately concrete: generic advice ("test your code", "watch performance") is worthless — the value is in which specific things break, why, and the exact habit that prevents each. Every rule here was paid for by a real failure.

The one idea to keep:

Software survives real use not because of a clever algorithm, but because its state is cleanly separated, every constant that gates behavior was measured rather than guessed, correctness is checked by invariants you can actually run, and the system is assembled in isolated stages you gate one at a time. Correct behavior is discovered through instrumentation, not asserted by hope.

The most expensive bug in most builds is the same one every time: a magic number chosen by intuition instead of measurement. Internalize P3 and you have already avoided the failure that causes silent collapse, dead output, and days of vibes-based tuning.

---

The nine principles

P1 — Separate three kinds of state; never persist what you can derive

Almost every non-trivial program has exactly three kinds of state, and conflating them is the root of a whole family of bugs:

• Source of truth — inputs, user decisions, config, the seed. Persisted.
• Derived — anything computable from the truth (indexes, caches, layouts, aggregates, similarity scores, resolved graphs). Recomputed, never saved.
• Ephemeral — session-only (cursor, hover, in-flight buffers, UI state). Dies with the process.

Rule: never persist what you can derive (it goes stale and breeds migration hell); never derive what encodes intent (recomputing "the user dismissed this" destroys the decision). Route all derivation through one recompute path: mutation → recompute → present. One arrow, no partial-update bugs.

P2 — Keep a pure core, seed the randomness, make it reproducible

Keep the logic that decides things free of I/O — no network, disk, DOM, clock, or global mutable state reached from inside it. Inject those at the edges. Replace ambient randomness with an explicitly seeded PRNG. This is not purity for its own sake: a pure, seeded core runs thousands of times in milliseconds, headless, and reproduces exactly — which is the precondition for every other discipline here. The moment behavior is non-reproducible, you can no longer answer "did my change help?", because every run now differs for two reasons at once.

P3 — Calibrate every gating constant from printed data, never from intuition

This is the principle that pays for the whole file. Any constant that gates behavior — a threshold, timeout, retry count, batch size, cache TTL, pool size, backoff factor, similarity floor, rate — must be chosen by writing a tiny probe that prints its real distribution on realistic input, then reading the number off the printout. Not guessed.

Two real collapses, same root:

• A similarity threshold guessed at 0.28 when real values ran 0.05–0.30 produced an application that silently did nothing — zero output, and no error to point at.
• A resource drained 27× faster than it refilled collapsed a system whose global averages looked perfectly healthy — the exhaustion was local and hidden.

Ten minutes of measurement replaces days of guessing. Always print human-readable context beside the number (the actual records beside the scores, the actual keys beside the counts) — the number alone can't tell you whether it's right.

P4 — Prefer composable, data-driven rules over special-cases and global reads

If you catch yourself writing if (globalTotal > N) or special-casing one situation, stop: you are hand-authoring a macro behavior that should fall out of the design, and it will be brittle. Prefer many small local rules expressed as data (tables, parameter vectors, weighted signal lists) over sprawling type-specific if/else code. Data is editable, testable, and can't hide special cases in a branch you forgot. When several weak signals exist, stack them with an explicit priority and merge — each layer stays debuggable alone.

P5 — Assert invariants, not outputs; build the harness before the UI

You often can't assert an exact output (it's input-, seed-, or corpus-dependent). You can assert the properties that must hold for any correct run, and you should build the thing that checks them before building the interface:

• Nothing is NaN/null-where-forbidden; every quantity stays within its bound.
• Bookkeeping is consistent (a fresh scan equals the maintained count).
• Reversible operations round-trip exactly: save → load → continue is identical (two classic bugs live here — restore the RNG/cursor state last, and don't round-trip through a lossy format if you need bit-identity).
• Intent is honored: a deleted/dismissed thing never silently reappears.
• Turn the fuzzy goal into a number. "Does it cluster / converge / stay stable?" → a metric that's ~baseline for a degenerate run and clearly higher when the property holds. Now "it works" is a regression test, not a vibe.

Ship the harness inside the artifact when you can (a self-test mode that runs assertions and emits a machine-greppable PASS/FAIL verdict). It converts "I believe it works" into something checkable — exactly the step that gets skipped.

P6 — Isolate → stabilize → compose → tune → verify, and gate every step

Build in this order, each stage with an explicit exit criterion, and refuse to proceed past a failed gate:

1. State + core loop written; nothing invalid after N iterations.
2. Isolate one part and make it correct alone. Calibration and boundary bugs surface cleanly here, un-buried by everything else.
3. Add the next part; test the pair. Coupling bugs surface here (see P8).
4. Compose the whole; tune for the character you want, not merely "runs" — and tune on a table (a parameter sweep printing outcomes per cell), not by eyeballing.
5. Only now build the interface and controls.
6. Adversarial pass: edge inputs, extreme parameters, round-trips, long runs.

Most failures are diagnosed 10× faster in an isolated subsystem than in the whole assembly. Skipping "isolate" is the most common self-inflicted wound.

P7 — Every automated judgment carries its reason; destruction needs a guard

If the system decides something for the user — a match, a suggestion, an auto-fix, a merge — the function that computes it must return the evidence with it ({result, why}), never the bare result. A decision with no reason reads as random; the same decision labeled with its cause reads as intelligent, and is debuggable. If you can't produce a one-line justification, don't ship the judgment. Enforce the asymmetry: freely create reversible structure, but any destructive or irreversible action (delete, overwrite, apply-in-place) requires an explicit confirmation.

P8 — Coupled constants can be jointly impossible; check interacting ranges

Two individually reasonable numbers can be jointly contradictory. A real one: a contact radius of 18 nested inside a separation radius of 23 made an interaction geometrically impossible — agents were pushed apart before they could ever meet — though each number looked fine alone. Whenever two constants interact (a timeout vs. a retry budget, a buffer vs. a chunk size, a floor vs. a cap, a lower threshold vs. an upper one), write down the relationship they must satisfy and assert it. Isolating subsystems (P6) is how you expose these.

P9 — Design the degenerate case; make even the worst state coherent

The boundaries are where things break or look dead, and where users decide the thing is alive or broken:

• Empty / n=0,1,2 / cold start: every function must degrade gracefully, not divide by zero or render a blank void. A crafted starter state that makes the interesting behavior demonstrably fire beats any amount of documentation.
• Collapsed / degenerate steady state: choose a design whose worst case is still coherent (a running-but-reduced system beats a frozen or corrupt one). This is the difference between something that feels alive after twenty minutes and something that settles into a dead equilibrium.

---

Applying this inside a coding session

This discipline is most valuable injected into an AI-assisted build loop, where the default failure mode is confidently producing a plausible-looking artifact that breaks on contact with reality. To counter that:

• Draw the P1 state table and name the P3 gating constants before writing code. This alone removes most downstream pain.
• Give one job per turn. "Build the pure core and pass its invariants," then separately "probe the constants and report the distribution," then "add the interface." Long "build and tune and verify it all" prompts are where quality drifts.
• Make measurement non-optional. Demand the probe's printed output in the reply before any threshold is chosen. A model (or a person) will confidently hardcode > 0.5 unless forced to look at the data.
• Demand evidence-carrying returns (P7). Contracting every decision as {result, why} forces better logic, because vague logic can't produce a concrete reason.
• Gate on invariants, not vibes. Refuse to advance a stage until its exit criterion prints green. The single biggest quality lever is not continuing past a failed gate.

The throughline: a modest model executing a strong, explicit structure beats a strong model improvising. This file is that structure — the principles say why, the build order says in what order, and the invariants say when you're actually done. The hard part was never the code. It was knowing what to check, and in what order.

---

Distilled from real builds — the failure modes named above (a threshold that silenced an app, a drain/refill mismatch that hid behind healthy averages, a pair of radii that made an interaction impossible) all actually happened and were actually fixed. The specifics are the point; keep them.