docs: name the defect shape that produced eight issues in one day #592

Merged

coilyco-ops merged 1 commit from docs/a-default-that-reads-as-an-answer into main

2026-08-13 16:42:01 +00:00

coilyco-ops commented

2026-08-13 16:39:39 +00:00

Member

closes #591

Eight issues in this repository today were one shape. Every instance read as correct and none of them failed anything.

The shape

A value has a default, an empty state, or a fallback. A reader cannot tell that state apart from a real measurement, so they read it as one.

#520  a cache hit and a network round trip, as one count
#533  the production deployment and every evaluation run, as one service.name
#357  a tool the model declined and a tool never offered, as one message
#534  "nothing was cached" and "not everything was cached", as one boolean
#587  an absent attribute and an old pod, as one empty string
#589  a nameless tool and a tool named after its server
#292  an empty failure_cause and a broken one
#568  "this branch is green" and "this merge is green"

Four habits

Ask what the default looks like from the outside — not whether it is correct, but whether a reader can tell it apart from a real value. Prefer a distinct state to a plausible one. Check a field's own history before believing it, because "empty" and "newer than the image" look identical in a query. And preserve the old series when a meaning changes.

Why a document and not a check

There is no mechanical form of "a reader would misread this". It is a review habit, and the eight rows are the evidence that having it produces different answers.

One fix pattern is worth the space it takes: #534 was fixed by adding mcp.tools.configured and mcp.tools.reached beside the boolean rather than by changing what the boolean meant. Changing a live attribute's meaning is how these get created. I nearly did exactly that on #520 — my closed PR set mcp.tools.cached as an int while main had just set it as a bool, which would have made the attribute unqueryable and recreated the defect I was fixing.

70 lines, 3438 characters, inside both caps with room. ward exec gate green.

closes #591 Eight issues in this repository today were one shape. Every instance read as correct and none of them failed anything. ## The shape A value has a default, an empty state, or a fallback. **A reader cannot tell that state apart from a real measurement**, so they read it as one. ``` #520 a cache hit and a network round trip, as one count #533 the production deployment and every evaluation run, as one service.name #357 a tool the model declined and a tool never offered, as one message #534 "nothing was cached" and "not everything was cached", as one boolean #587 an absent attribute and an old pod, as one empty string #589 a nameless tool and a tool named after its server #292 an empty failure_cause and a broken one #568 "this branch is green" and "this merge is green" ``` ## Four habits Ask what the default looks like **from the outside** — not whether it is correct, but whether a reader can tell it apart from a real value. Prefer a distinct state to a plausible one. Check a field's own history before believing it, because "empty" and "newer than the image" look identical in a query. And preserve the old series when a meaning changes. ## Why a document and not a check There is no mechanical form of "a reader would misread this". It is a review habit, and the eight rows are the evidence that having it produces different answers. One fix pattern is worth the space it takes: **#534 was fixed by adding `mcp.tools.configured` and `mcp.tools.reached` beside the boolean rather than by changing what the boolean meant.** Changing a live attribute's meaning is how these get created. I nearly did exactly that on #520 — my closed PR set `mcp.tools.cached` as an int while main had just set it as a bool, which would have made the attribute unqueryable and recreated the defect I was fixing. 70 lines, 3438 characters, inside both caps with room. `ward exec gate` green.

coilyco-ops added 1 commit

2026-08-13 16:39:40 +00:00

docs: name the defect shape that produced eight issues in one day

ci / image-build (pull_request) Successful in 24s

Details

ci / test (pull_request) Successful in 45s

Details

ci / publish-echo-image (pull_request) Has been skipped

Details

ci / publish-observed (pull_request) Has been skipped

Details

b4d99f36e4

A value has a default, an empty state, or a fallback, and a reader cannot tell
that state apart from a real measurement. Nothing errors, no gate goes red, and
the number is plausible.

Eight issues today were this: a cache hit and a round trip as one count, the
production deployment and every evaluation run as one service name, a declined
tool and an unoffered one as one message, an absent attribute and an old pod as
one empty string, a nameless tool and a tool named after its server, and a
green branch and a green merge.

Four habits, and the one that matters most is the cheapest: ask what the
default looks like from the outside rather than whether it is correct.

Written as a document rather than a check because there is no mechanical form
of "a reader would misread this". The instance list is the evidence that the
habit produces different answers than not having it.

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-13 16:39:40 +00:00

coilyco-ops merged commit 0326449cdf into main

2026-08-13 16:42:01 +00:00

coilyco-ops referenced this pull request from a commit

2026-08-13 16:42:02 +00:00

Merge pull request 'docs: name the defect shape that produced eight issues in one day' (#592) from docs/a-default-that-reads-as-an-answer into main

coilyco-ops referenced this pull request

2026-08-13 16:48:07 +00:00

before your message is not before this turn, so two claims still reach the member #598

coilyco-ops referenced this pull request

2026-08-13 16:48:23 +00:00