Skip to content
C.W.K.
Stream
Lesson 02 of 04 · published

One Sentence, Load-Bearing

~12 min · invariant, ethic, architecture, descriptive

Level 0Raw Ore
0 XP0/36 lessons0/12 achievements
0/100 XP to next level100 XP to go0% complete
"Assays value, never advises."

The invariant, and why it is first

Architecture documents in this family open with a list of invariants — the properties that must hold no matter what gets built later. Touchstone's first one is four words long: assays value, never advises. Everything automatic that the product shows is descriptive: the value, its date, its source, and its percentile context. No rankings. No buy or sell framing. No alert engineered to provoke action.

Putting it first is deliberate. An invariant that arrives on page four gets read as a preference. An invariant that arrives before the system context table gets read as a constraint on everything below it — which is what it actually is, because every feature proposal after that point has to pass through it.

What makes it enforceable rather than aspirational

Plenty of products have a sentence like this in a design doc and violate it by the third sprint, because a sentence in a document cannot stop a pull request. Two things make this one hold.

The first is that it is stated as a review test, not as a value: enforced by review of every new surface against this sentence. That converts an abstract ethic into a concrete question with a yes-or-no answer — does this new card rank anything? does it use urgency language? does it imply a forecast? A question you can actually ask about a diff is worth ten paragraphs of principle.

The second is that the sentence has teeth in the code. You will see functions in this quest that could easily have returned a signal and deliberately do not: a regime classifier that returns a phrase like ELEVATED instead of a score-to-act-on, a change digest whose own docstring says ordering is an ordering, never a ranking of importance. The discipline is written where it can be read by the next person to touch the file.

An ethic that cannot be checked on a diff is a mood. "Be responsible with financial data" cannot fail review. "Does this surface rank, signal, or imply a forecast?" can. When you want a value to survive contact with a growing codebase, restate it as a question a reviewer can answer while looking at one file.

The line is initiation, not silence

An important subtlety, inherited from the portfolio sibling: this is not a rule that the software must be useless when asked a real question. The boundary sits between unsolicited and requested. Every surface the app renders on its own stays strictly descriptive. When a human deliberately opens the assistant surface and asks a direct question, they get ordinary judgment, because they initiated it.

That distinction is what keeps the rule from collapsing into disclaimer theater. A tool that constantly volunteers advice is a nag. A tool that refuses to answer a direct question is merely broken, and usually gets replaced by something worse. The restraint belongs on the automatic surface, where nobody asked.

The family pattern. This is the third sibling to hold the same shape. The portfolio app observes but never recommends a trade. The health app observes but never diagnoses. The valuation engine assays but never advises. Three domains where automated confidence is most tempting and most expensive — and one inherited posture, restated in each domain's own vocabulary.

Code

The review question, applied to real feature proposals·text
PROPOSAL                             VERDICT   WHY
----------------------------------   -------   ------------------------
"Show the percentile of each gauge"  PASS      states position in a
                                               stated reference set

"Sort gauges by how extreme"         PASS*     *ordering only, and the
                                               code must say so

"Highlight the 3 most attractive"    FAIL      'attractive' is a ranking
                                               with an implied action

"Alert when CAPE crosses 40"         FAIL      a threshold engineered to
                                               provoke; also a forecast
                                               in disguise

"Show what moved most since
 yesterday"                          PASS      magnitude of observed
                                               change, no threshold

# The test is not 'is this useful?' — all five are useful.
# The test is 'does the app initiate a judgement nobody asked for?'

External links

Exercise

Write the four-word invariant for a tool you have built or used, then write the review question it implies. The invariant should name what the tool does and what it structurally refuses. Then take three features that tool actually has and run them through the question. If none of them fail, your question is too soft — a test that nothing fails is not a test.
Hint
Good invariants are verb pairs: observes/never recommends, assays/never advises, records/never authors. The refusal half is the load-bearing half, and it should be something a reasonable person would otherwise want to build.

Progress

Progress is local-only — sign in to sync across devices.
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign inPlease sign in to comment.

No comments yet — be the first.