Eight issues in one day were the same defect shape: a default that reads as an answer #591

New issue

Closed

opened 2026-08-13 16:39:09 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

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

Member

Filed by Angie (ENG, claude seat) to carry a document, so the doc has an issue to close rather than arriving unattached.

Eight separate issues in this repository today turned out to be one shape. Every instance read as correct, none of them failed anything, and several were believed and acted on before being caught.

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. Nothing errors, no gate goes red, and the number is plausible.

The instances, all measured today

what	the indistinguishable pair
#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"

Two of those were mine and one was a fix I nearly shipped that would have recreated the defect it was fixing — I set mcp.tools.cached as an int while main had just set it as a bool, which would have made the attribute unqueryable.

What the document says to do

Four habits, all cheap:

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. If they cannot, that is the defect, before any wrong behaviour exists.

Prefer a distinct state to a plausible one. An explicit unknown beats a zero; a refused call beats a silent fallback.

Check the field's own history before believing it. "This field is empty" and "this field is newer than the image that wrote it" look identical in a query. That mistake was made twice today and caught twice.

Preserve the old series when a meaning changes. A number that means something different than it did last week, while reading identically, is worse than a wrong number.

Why a document rather than a check

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

The fix pattern that worked repeatedly is worth stating too: #534 was fixed by adding fields beside the boolean rather than by changing what the boolean meant. Changing a live attribute's meaning is how these get created in the first place.

**Filed by Angie (ENG, claude seat)** to carry a document, so the doc has an issue to close rather than arriving unattached. Eight separate issues in this repository today turned out to be one shape. Every instance read as correct, none of them failed anything, and several were believed and acted on before being caught. ## 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. Nothing errors, no gate goes red, and the number is plausible. ## The instances, all measured today | what | the indistinguishable pair | |---|---| | #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" | Two of those were mine and one was a fix I nearly shipped that would have recreated the defect it was fixing — I set `mcp.tools.cached` as an int while main had just set it as a bool, which would have made the attribute unqueryable. ## What the document says to do Four habits, all cheap: **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. If they cannot, that is the defect, before any wrong behaviour exists. **Prefer a distinct state to a plausible one.** An explicit unknown beats a zero; a refused call beats a silent fallback. **Check the field's own history before believing it.** "This field is empty" and "this field is newer than the image that wrote it" look identical in a query. That mistake was made twice today and caught twice. **Preserve the old series when a meaning changes.** A number that means something different than it did last week, while reading identically, is worse than a wrong number. ## Why a document rather than a check There is no mechanical form of "a reader would misread this". It is a review habit, and the eight rows above are the evidence that it produces different answers than not having it. The fix pattern that worked repeatedly is worth stating too: **#534 was fixed by adding fields beside the boolean rather than by changing what the boolean meant.** Changing a live attribute's meaning is how these get created in the first place.

coilyco-ops referenced this issue from a pull request that will close it,

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

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

coilyco-ops closed this issue

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