design-protocol

name	design-protocol
description	Design Protocol 1 — a design is a testable HYPOTHESIS about an invariant, not a plan you execute. The DESIGN-mode counterpart to the engineering-rigor skill (which routes here for the design half). USE THIS whenever you are about to commit to a load-bearing design — a core representation, runtime, memory model, codegen, a public contract, a data format, or any algorithm that will carry weight: name the ONE invariant, count its re-assertion sites, build the cheapest probe that could FALSIFY each load-bearing claim, then build and validate against the written prediction. And for exact-invariant domains where you cannot even form the invariant (geometry, caching, hashing, store/memory lifetime, round-trips), flip to the constructive instrument — plot a concrete instance of the ANSWER and read the invariant off it. Reach for it when a design feels too clean, when you keep reaching for an approximation, or whenever you catch yourself about to build the first coherent design without probing it.
user-invocable	true

Design Protocol 1 — A Design Is a Testable Hypothesis

Transferable — written so an agent in any codebase can read it cold and apply it. The examples are evidence, not prerequisites: skip them and the procedure still stands.

---

The thesis

A design is not a plan you execute. It is a hypothesis about an invariant — a claim that some single rule makes every case (including the ones you never tested) behave correctly for the same reason. A hypothesis can be wrong, and you can test it — the same epistemics as a bug's root-cause hypothesis, one level up:

Bug	Design
has a root-cause hypothesis	has an invariant hypothesis
tested with a boundary matrix (probe the cells)	tested with probes on its claims (try to falsify each)
"I can't see the root" = "the matrix isn't finished"	"I can't name the invariant" = "it isn't a design yet"
the fix is the proof	the build is the proof

The failure this prevents is shipping a design as a confident assertion — a story that reads correct in prose and breaks at the first case the prose didn't look at.

Why a probe, not more care

The generative capability is real — a coherent design, correct load-bearing predictions. Its characteristic failure is over-reach: making the design cleaner / bigger / more unifying than the domain warrants — and that failure is invisible to introspection, because it presents as elegance. So brittleness here is a sight failure, not a values failure: you are not choosing fragility, you genuinely cannot see the false absorption from the desk. The cure is therefore not "more care" (a values lever — it does nothing for a sight gap) but better eyes: a test that can falsify the claim. The design-probe is to a design what the boundary matrix is to a bug.

Earned the hard way. A real design's invariant was framed plausibly but wrong, and it "also subsumed" an unrelated bug it actually didn't — both read as correct in prose; re-reading caught neither, only probing the specific claims did. And the inverse: a design shipped without probing, whose own plan said "one chokepoint that 18 sites route through" — a spray wearing the word chokepoint — shipped as 18 bypasses and a silent mismatch.

---

The other half — when you cannot form the invariant at all

Over-reach is the failure of a design you already have — a candidate invariant, too clean, that a falsifying probe can break. It assumes the generative step has succeeded. There is a symmetric failure one move earlier, where it has not: you cannot state a candidate invariant at all. Step 1 below names this state — "a pile of cases, not a design yet" — but treats it as a stop sign. On one class of problem it is the main event.

Exact-invariant domains. In geometry, caching / serialization, hashing, store / memory lifetime, and protocol round-trips, the correct design is not an open space to explore — it is a single construction that already exists and must be recovered. There the characteristic failure is not over-reach but failing to generate the right candidate: the mind reaches for an approximation (geometry — fit a line, bucket the angles, smooth the wobble) or chases the symptom (a store desync surfacing as three different corruptions). Both are iterating toward an answer that already exists exactly — motion that never converges, because the target is a point, not a region.

Same epistemics, opposite instrument. This is still sight, not willpower — you cannot will the invariant into view, and "think harder" does nothing for the gap. But the instrument here is constructive, not falsifying: a falsifying probe needs a claim to break, and you have none. The generative instrument is to plot a concrete instance of the answer — the exact target output / state for one specific input — or build the cheapest thing that produces it (a throwaway prototype, a round-trip test), then read the invariant off it. The construction you could not name in the abstract is legible in one worked instance.

• Caching. A startup-cache desync was symptom-chased across manifestations until the target store state after a round-trip was plotted concretely — the invariant then read out at once (the round-trip must reproduce every binding identically, the synthetic wrappers included). A one-line fix behind a large discovery cost.
• Geometry. A grid wall-straightener resisted eight approximations (line-fit, angle-buckets) against an "exact, not an approximation" spec, until the construction was drawn as a plotted end-result (subdivide each cell into triangles; keep the band the boundary cuts, drop the full-in / full-out ones). Only pinpointable after a throwaway prototype produced it — then ported unchanged.

When the answer already EXISTS — capture its artifact and diff. The cheapest "plot the answer" is a working sibling that already produces the construction for a near-identical case. Then you neither prototype nor theorise: capture the sibling's artifact and your broken one's — into files, not glances — and diff. The residual divergence is the construction to recover; you read it off the diff, not out of your head. Three captures sharpen it: BEFORE (your change off) → NOW (your change) confirms you changed what you meant; NOW → PROVEN-sibling isolates the bug. The failure this prevents is symptom-chasing a near-miss: holding a theory of the difference without the capture, patching one manifestation, and finding the next — motion near a point it never lands on. Earned. A borrowed store-delivery corrupted only under allocation pressure; three theories held without a capture — a stride-type, a missing wrapper op, a lifetime flag — were each wrong. Capturing the proven sibling (a simpler shape that survives the same stress) beside the broken output showed the one real difference in a line: the proven path delivered into a canonical owned buffer, the broken one reused an incidental local as the buffer — a dep the lifetime analysis never tracked as the return, so a later allocation reused its slot. The captured diff landed on the point the three patches kept circling. (For a captured-artifact domain — IR, serialized bytes, store state, protocol frames — this beats prototyping: the answer is already running; make yours byte-equal to it.)

A sharp distinction from the bug side. The matrix law is "the truth is in the class, invisible in the instance" — beware acting on one instance. This does not contradict "plot one concrete instance," because the instances are opposites: an instance of the problem / symptom is the trap (it hides the class it belongs to); an instance of the answer / end-result is the instrument (you read the invariant — and therefore the class — off it). One misleads, the other generates.

Where this sits. It runs before step 3's falsification and moves step 5's build forward: for an exact-invariant domain the build is not the last probe but the first, generative act — the construction is named by building the cheapest version, that invariant is then probed (steps 3–4), and only then is the real one built. The cheap prototype is where the design gets pinned, not merely confirmed.

---

Write the doc before the code — the failure-paths are where the invariant surfaces

The design doc is not after-the-fact write-up. Writing it is the generative act that surfaces the invariant and the requirements — cheaply, before code commits you to an unstated one. Enumerating the failure paths (every way it breaks) and naming what must hold across the boundary (the requirements) is exactly where the load-bearing invariant becomes nameable (step 1 below). Code-first skips that enumeration: you silently adopt the narrowest invariant you happened to see and then discover the real one by whack-a-mole — each patch fixes one case and reveals the next the prose never listed. The doc is the cheapest place to find the right invariant; code is the most expensive place to discover it was the wrong one.

Earned. A native-link StableCrateId collision was "fixed" by build-identity keying — rebuild the package so its shared deps match the consumer's — coded before the design was written down. It fixed libloading (a flags mismatch), then log collided (a profile mismatch), and the next would have been build-script reproducibility: a symptom chased one collision at a time. The load-bearing invariant — keep the API identity (the C-ABI contract) separate from the Rust part (the package's private internals), so the latter never enters the consumer's link — only became visible once the failure paths were written down and the two identities were named on the page. Matching is whack-a-mole; the doc made separation legible, and writing it first would have skipped the dead-end build entirely.

So for a load-bearing design: write the doc first — the failure paths, the cross-boundary requirements, the candidate invariant — then code. Not a full spec; the minimum that forces you to enumerate how it breaks and what must hold. The enumeration is the instrument: the class you cannot see from the desk is legible the moment you are forced to list its members. (This sits before step 1 — it is how you reach a nameable invariant — and complements the other half: when you cannot state the invariant, plot a concrete instance of the answer or write the failure paths down; both make the construction legible.)

---

The protocol

Run it when a design is load-bearing — an algorithm that will carry weight (a core representation, runtime, memory model, codegen, a public contract) — or when something feels fragile, or when the domain is exact-invariant (a construction to recover, not a space to explore — see The other half). Not reflexively (see Keep it light).

1. State the design as one invariant. One sentence: under what single rule does a case you never tested behave correctly, for the same reason the tested ones do? If you cannot name it, it is not a design yet — it is a pile of cases; on an exact-invariant domain the way out is generative, not more thinking — plot a concrete instance of the answer and read the invariant off it. Naming it is the difference between a matrix that is confirmatory (evidence an invariant holds) and one that is constitutive (the cells are the only reason it works).

2. Count the re-assertion sites — the prospective tell. How many independent sites must re-state the invariant for the design to be correct? If the answer is N > 1 and omitting it at a site is silent (a wrong result, not a compile error), N is the brittleness, known now, before any code. "One chokepoint that 18 sites route through" is a self-contradiction; the prediction has already failed. Two cures, attacking the two factors: collapse N toward 1 (a real chokepoint — one place every path consults), or make omission loud (a type or guard that turns forgetting into a compile error). Drive N × silence toward zero.

3. Probe each load-bearing claim — try to falsify it. For every claim the design rests on ("X is subtractable", "the buffer is Y", "this also handles Z"), write the cheapest test that could prove it false — a throwaway probe, a targeted code read, one boundary case. Expect to falsify. Re-reading the prose is not a test; the prose is where the error hides.

4. Attack your cleanest claim specifically (the over-unification guard). The most dangerous error is the elegant absorption of a case that is not really in the family — the failure mode that presents as success. Every "…and it also handles X" is a claim to falsify, not a bonus to celebrate. Compressing genuinely-distinct cases under a false invariant is itself brittleness (wider than the domain); it breaks when the cases assert their real differences.

5. Build it (new code) or read it fully (old code). Either way you now have the actual shape to compare against the prediction. (Auditing an existing subsystem is the same protocol: predict what a cohesive version would cost, then read it — the gap diagnoses the substrate.)

6. Validate against the written prediction — the build is the last probe. A divergence (most often bigger / more mechanisms than predicted) is an alarm, not a verdict. Route it to the search: is the extra length accidental (N mechanisms for one family — a missed invariant; find it and the code collapses back toward the prediction), essential (genuinely N families, no invariant to find; the surprise just taught you a domain axis you couldn't see — record it), or over-broad (the rule is correct but rewrites more producers than the defect touches — a consumer already holds the per-case info, so narrow it to the broken path instead of normalising every producer)? No metric decides this; only understanding whether the cases share a deeper structure.

The alarm gates the decision, it does not merely log. Whichever step trips, the fired alarm routes to the search before the approach is chosen. "Thread the fix through all N sites" stays legal — but only ever as the search's conclusion, never the default. The sharpest failure is not missing the alarm but seeing it and overriding it for momentum. (When the alarm is a measurement that jumped — a false-positive count that leapt — the gate is the ratchet: flag the divergent approach, don't revert the clean one. See engineering-rigor § "Building a noisy check to clean".)

---

The two ways to fail (teach both — they are symmetric)

Failure	What it is	The cure
Ignore the alarm (under-unify, ship the spray)	N mechanisms for what is really one family — a missed invariant; or the alarm fired and lost to momentum	the alarm must gate, not log (step 6); count the sites (step 2)
Obey it blindly (over-unify)	one mechanism forced over genuinely N families — a false invariant that breaks when the cases assert their differences	probe the cleanest claim (steps 3–4)

The probe is what distinguishes them: it tells you whether the cases actually share the invariant. Under-unification is caught by counting sites; over-unification by trying to falsify the unifying claim.

But over-unification has a second face a falsifying probe misses: a unifying claim that is true — every case really fits — yet applied wider than the defect. A correct universal rule rewritten across every producer to repair a fault that lives in one consumer path is over-reach by blast radius, not falsehood; no probe fires, because the claim holds, and the re-assertion count can be N = 1 (one place adds it to all), so step 2 stays silent too. The check here is informational, not falsifying — before committing the universal form, look for a special circumstance in the implementation context (a consumer / runtime that already holds the per-case information) that lets the broken path adapt while the producers stay untouched. The correct universal story is exactly what suppresses that look; the cue to run it is the scope ballooning past the size of the failing domain — universal stays the right default, but special circumstances still occur and have to be looked for, not assumed away.

---

Keep it light — the procedure must not consume the judgment it serves

The cheap, always-available sensor is the tell: "this is longer / absorbs more than I expected for what it does." Code longer than it should be trips the worry before any matrix, profile, or crash — because the robust design covers N cases with one mechanism (it lands short) and the brittle one covers them with N mechanisms (it accretes as bulk, then as runtime cost). This is robustness by subtraction: the deep reason the shorter version is usually the more robust one — correctness-by-construction from a single nameable invariant, won by removing cases, not guarding them.

The tell has an earlier, more visceral form than final length — the implementation stutters. When the build fights you (you reach for a workaround to make the chosen mechanism fit, the scope grows again mid-build, you are on the third re-read of code that still won't sit right), that friction is the approach working against the grain — a solution that fits the domain rides the existing structure and goes smoothly. Route the stutter to the search (the over-broad check above — is a special circumstance being fought?), not to pushing harder. Reading the stutter as "this is just hard" rather than "the frame is wrong" is the characteristic miss: the friction WAS the signal, and it fires before the length does.

But the tell says look, not what you will find — sometimes length is essential (genuinely N families, or an invariant deliberately spelled out so it is explicit rather than hidden in cleverness). So the tell triggers the search; it never dictates shortening.

The full write-down-predict-probe-validate procedure fires only when the tell trips on something load-bearing — never reflexively per function. An ever-on checklist would be friction and would burn the very capacity the essential-vs-accidental judgment depends on. Writing the prediction down is a load reducer, not a tax: it moves the prior onto the page so working memory is freed for the building and the judgment. Design is intrinsically heavy — it holds the whole composition space at once — so the page is where you put down what you would otherwise drown carrying.

---

The residual

The protocol only covers axes you know to vary. The axis invisible at design time — the composition no probe imagined — survives any discipline; only real use reveals it. That is why the method has a second engine: the dogfood loop — real consumers, not toys — is what converts an unknown axis into a known one, and each harvested lesson is appended to the axis list your next design's matrix varies. This protocol makes the visible axes safe; the dogfood loop grows what is visible.