What 149 rounds of review still missed

The previous post is the flattering version of the same afternoon: a shopping question turned into a product, and the product told me not to shop. This is the other version.

Over three and a half hours I sent 149 messages reviewing a tool being built in front of me. It was, genuinely, the most attentive code review I have ever given anything. The result shipped with a promise on its README that five of its nine languages could not keep, and I never saw it.

I want to be precise about both halves, because the gap between them is the actual lesson.

What the review caught

Not nitpicks. Real things, most of them on the first pass:

• A recommendation that said *consider 24 GB or more* — I asked whether that number was detected or hardcoded. It was hardcoded. The fix was still hardcoded, so I asked again: what happens when 64 GB is the normal tier?
• Section markers written as `【Memory】` when the sibling tool in the same family uses a different convention entirely. Two tools, one family, two vocabularies.
• The English output printing Chinese words in it.
• Text wrapping wrongly in the terminal, which turned out to be the classic one: CJK characters take two columns and `printf` pads by bytes, so every column after a Chinese label lands in the wrong place.
• *Doesn't "average" already imply history?* — killing a redundant word in a label I had read forty times.
• Emoji everywhere, which I said looked cheap, and which are now gone family-wide.

I also had to say *stop agreeing with me* five separate times. Every one of those came immediately after I floated an opinion. That is worth its own post, but note the shape: the reviewer had to keep manually installing his own adversary.

By the end I had read every screen the tool could produce, in two languages, repeatedly.

What shipped anyway

Then I picked it up a day later with fresh eyes and a different job — packaging it for release — and found this:

• **The nine-locale claim was true of the nouns and false of the sentences.** `Storage`, `Batería`, `メモリ` all delivered. But every verdict line and the entire recommendation section fell through to English for Spanish, German, French and Portuguese. A Spanish reader got `[ PASS ] Batería: Health good (89%)`.
• **Simplified Chinese was reading Traditional Chinese** — a Simplified reader met Taiwan vocabulary throughout the report.
• **`--json` shipped without the verdict.** The tool exists to produce a verdict. Its machine-readable output had eleven readings and no answer, so any consumer had to re-derive the thresholds and would eventually disagree with the tool about the same machine.
• **`"battery_health_pct": "89"` sat next to `"swap_used_mb": 2889`** — the same kind of fact, two types — and an unavailable reading was the *string* `"N/A"`, which anything doing arithmetic turns into a silent zero.
• **No CI**, for a tool whose README promised macOS *and* Linux.
• **The changelog was still at 0.1.0** while the script had reached 0.6.5.

The pattern, once you see it

Everything the conversation looked at is excellent. Everything the conversation did not look at was never built.

That is not an accident and it is not laziness. Look at what I was reviewing: **output**. Wording, spacing, alignment, redundancy, punctuation, tone. Every one of those is visible on a screen I was already reading.

Now look at the list of what shipped broken. To catch the Spanish gap I would have had to run the tool in Spanish. To catch the JSON gap I would have had to parse the JSON instead of reading the report. To catch the CI gap I would have had to push to a second platform. None of those are on the screen. No amount of *reading harder* reaches them.

And here is the uncomfortable corollary. A weak review leaves visible flaws, and visible flaws warn you that there are invisible ones. A great review leaves a surface with no seams — so you conclude the inside matches. **The better the review, the more complete the illusion.**

What actually closed the gap

Rulers that read structure instead of appearance.

The obvious i18n check — *does every key return something in every language?* — cannot see a partial translation at all. A missing locale falls through to the `*)` branch and returns English, and English is very much *something*. That check would have passed on every broken version above.

The one that works reads the shape instead: a key whose body opens `case "$SS_LANG"` is claiming per-language text, so every locale must appear as a branch label. No exception list, nothing to maintain — and it is why the code now says `en-US|*)` everywhere. One label meaning both "English" and "any language we have not heard of" is precisely what made the gap invisible.

The newest one is a lint for localization *voice*, and its first real run is the best evidence I have for this whole post. It went over eleven pages I had personally reviewed and found a Chinese word sitting in the Japanese copy, and four entries still written in **English** on all three Chinese, Japanese and Korean index pages — twelve descriptions, on pages whose entire job is to be read in another language. Not a subtle register problem. English text on a Chinese page, which had survived a careful human read.

Two of its own rules were wrong on that first run, incidentally, and both looked exactly like findings. That is the sibling lesson about machine verification, arriving from the other direction: a suspiciously round number across two files is the fingerprint of a broken ruler, not a broken page.

The rule I would give myself

**Review by reading catches everything on the screen and nothing behind it. For everything behind it, build a ruler and prove it can fire.**

Not "write tests" — I had tests. Prove the check can *fail*. The i18n gate that shipped was green because it could not be red. The lint that was clean was clean because nothing in it was looking. Until you have watched a check catch something you deliberately broke, all you know is that it is quiet.

The clearest example I have of that is not in this tool at all. It is on the e-ink tablet described in the next post, where a script shouted into the void for three days and reported success every single time, because the line that called a dead service ended in `2>/dev/null`.

The boring footnote

Both tools from this story are open and readable end to end: sheerstatus and sheersweep, MIT, single-file Bash, no daemons, no telemetry. The rendering rules and the lints that enforce them live in signet, which exists because three command-line tools independently grew the same vocabulary and then drifted on it.