WAYS OF WORKING · APPLIED NINO CHAVEZ

A registry for what
grep can't find.

Some facts a codebase depends on are invisible to search — the code compiles, the tests pass, and the behavior is still wrong. The technique: write those facts down in one place, once, and enforce the mechanical ones so they can't rot.

invariant #22 · scoring

matches.team1_score is a rally-point total (the sum of set scores) — not set wins.

Imported tournaments stored set wins there: a 2 where 42 belongs. Invisible in the match display — it renders the same — but it silently turns every standings +/− into a set differential. Grep the column and you find a healthy integer. Nothing looks wrong.

→ or scroll to advance · ← to go back

02 THE PROBLEM

Search finds topology, not truth

Grep is great at "where does X live" — routes, tables, functions. It's blind to the facts that make you confidently wrong: a column written but never read, a flag whose two values are identical to the runtime, a boolean that only means something in one mode, an environment where "local" silently means production.

These don't announce themselves. An agent (or a teammate, or you next month) reads the code, finds nothing amiss, and ships the bug — often the same bug, because the correction from last time evaporated. The fix is to stop re-deriving the fact and start recording the conclusion.

03 THE ENTRY

Write the fact, the trap, and the guard

A good entry is three things: the load-bearing fact, why it's a landmine, and what enforces it. Here's the archetype — a column that read healthy and lied:

invariant #1 · registration

A tournament accepts public self-registration iff registration_mode === 'open' AND registration_open === true. The mode is authoritative; the boolean only pauses within open mode.

Why it's a landmine: registration_mode was originally write-only — set at creation, derived once into the boolean, then never read again. Grepping the column showed a healthy NOT-NULL column with a CHECK constraint; the runtime ignored it and gated solely on the independently-toggleable boolean. An invitation tournament whose boolean drifted true would silently accept public registrations.
enforced ▸ state-derive inv-registration-mode-source-of-truth · ADR-0001

Same shape, other traps: types edited in the gitignored generated file that never reach the client; teams.captain_user_id that also holds steward placeholders; the tournament status field that's deprecated for conditionals. None findable by grepping for a problem.

04 WHY IT PAYS

The conclusion, pre-paid once

"Re-deriving these facts from source costs context budget every session — a grep returns 60 lines of matches you then read 300 lines of source to interpret, to extract 4 facts. An entry here is the conclusion, pre-paid once. On a long-lived project where sessions drift and compact, this registry is the only artifact that lets session N+1 spend three lines of context where session N spent three hundred." rally-hq/docs/INVARIANTS.md — the registry's own rationale, verbatim

This is the case for writing it down even when the fact is already "in the code." The code is the source; the registry is the index of what's dangerous about it — read at session start in one line each, instead of re-mined from scratch every time an agent wakes up with no memory.

05 ENFORCE IT

Derive the status; never hand-edit it

Prose rots. So the mechanically-checkable invariants are declared once as checks in a catalog; a derive step runs them to generate live status, and the same catalog runs in CI so a broken invariant fails the build — not at the next manual check.

npm run state:derive · catalog/invariants.ts → docs/state/_state.md
inv-registration-mode-source-of-truth   COMPLIANT   as_of 5adc2f4
inv-db-type-authority                   COMPLIANT   as_of 5adc2f4
inv-no-component-dark-mode-override     COMPLIANT   as_of 5adc2f4
inv-auth-guard-build-skip               NON-COMPLIANT ← a new route dropped the build-skip
                                        ↳ CI test fails · the push is stopped

Now trust changes shape: a test-backed entry can be relied on outright — that's what enforcement buys. Everything else carries provenance — verified-against a commit — and gets re-confirmed before you lean on it.

06 THE SPLIT

Three surfaces, no duplication

The registry only stays honest because each kind of truth lives in exactly one place — and the grep patterns live in the catalog, never copied into prose that could drift from them.

Why it's dangerous

The narrative landmine — this registry. One line in the index, a paragraph in the entry. Read at session start; the human-facing "here's the trap."

Why we decided

The immutable rationale — the ADRs in docs/decisions/. Written once, never edited; the entry links to it rather than restating it.

Currently true

The generated status — docs/state/_state.md, COMPLIANT / NON-COMPLIANT + evidence + as-of-commit. Never hand-written; the derive owns it.Add a fact only when it repeats — and verify it against source that session.

07 HONEST LIMITS

The registry can lie too

Prose entries lag

A verified-against entry is only as fresh as its commit. It can quietly diverge from current source — which is exactly why the mechanical ones are pushed into CI and the rest carry a re-confirm-before-you-rely rule.

Most facts don't belong

The bar is high on purpose: true, non-obvious from one file, and costly to get wrong. Topology stays out — grep finds it fine. A registry that holds everything is just a second codebase to keep in sync.

It needs a registry about itself

The "how to add an entry" rules — number sequentially, never renumber, prefer a test to prose, verify in-session — are the meta-guard that keeps the registry from becoming the next thing that lies.A fact you can't check in CI carries a date, not a promise.

08 USE IT

Start the file the second time

If you never touch code

The pattern is just "write down the non-obvious thing that bit you, where the next person will look." A runbook line, a decision log, a 'why this is weird' note beats re-explaining it every quarter — and beats hoping everyone remembers.

If you're technical

Start the file the second time something breaks for the same reason. Record the fact, link the decision, and — if it's mechanically checkable — write the test and let CI hold it. Derive the status; never hand-edit "currently true."

If you build systems

Split the surfaces: narrative why, immutable decided, generated currently-true. Keep the check patterns in code, referenced from prose, never copied. The registry's whole value is being cheaper to trust than the source is to re-read.

write the conclusion, not the search test-backed = trust; verified-against = re-confirm start the file the second time, not the first
Colophon. An Applied technique companion to session demo 06, The Registry of Landmines. The entries, rationale, and enforcement model are quoted from a real 25-invariant registry — rally-hq/docs/INVARIANTS.md — with its catalog (state-derive) and CI test (state-invariants.test.ts); Blueprint ships the same register pattern to its consumers. The "re-confirm before you rely" discipline is the verification demo, demo 07, applied to the registry itself.