docs(playbook): three caches not one — confirm against server output; mxgw is the check-first outlier

This commit is contained in:
Joseph Doherty
2026-08-11 03:21:14 -04:00
parent f313c5e62e
commit 9dd288b3ad
+22 -2
View File
@@ -246,8 +246,13 @@ foundation branch merges — all branches build independently and compose at mer
also carry app-specific *shape* declarations that predate the sweep and that the kit does not
ship; mxgw's carried `border-radius: 5px; font-weight: 500; white-space: nowrap`, and a wholesale
delete would have silently dropped all three. Diff your block against the kit's before removing
anything: three of the five apps' blocks were pure sizing and safe to delete outright, one was
not, and the difference is invisible unless you look. Note also that a retained `border-radius`
anything: four of the five apps' blocks were pure sizing and safe to delete outright, one was
not, and the difference is invisible unless you look. Two of the four that were safe deleted
without diffing first and said so — they were lucky, not careful, and that is the same shape of
error as the ghost-class deletion §1a-1 guards against. **When a family-wide instruction lands,
check mxgw by hand first**: it is the member whose local CSS predates the kit by the most, so it
is the most likely to be the exception to any "all the apps have X" premise — it was the outlier
here *and* the one wrongly exempted from the scadaproj#2 modal sweep. Note also that a retained `border-radius`
should stay a **literal** rather than becoming `--bs-btn-border-radius` — `.btn-sm` redefines
that variable, so the switch would shrink small buttons to Bootstrap's small radius.
3. **Phantom tokens → a real class**, not a token alias. OtOpcUa's pattern:
@@ -364,6 +369,21 @@ Bootstrap's 16px, exactly what an unreached override looks like — so the natur
"fix" it by restoring the local rule you just deleted, entrenching the duplication the change
removed. Hard-reload first; only then trust a computed-style probe.
**A hard reload is not sufficient, and there are three caches, not one.** HistorianGateway hit a
second browser-side failure that survived the hard reload entirely: after running CSSOM experiments
on a page (deleting rules to preview a modifier), the tab's **DOM** kept the pre-experiment markup —
no `rail-btn-block` class on the element — while `curl` showed the server rendering
`class="rail-btn rail-btn-block"` correctly. It came within one report of calling a working fix
broken. A fresh tab settled it. There is also a third, non-browser cache: **NuGet's HTTP cache**,
which made `dotnet add package` resolve a just-published version as "not found, nearest is <prior>"
while the feed's registration index already listed it (`dotnet nuget locals http-cache --clear`).
So the rule is stronger than "hard-reload": **confirm against the server's own output before
believing the browser.** One `curl` of the page and one of the stylesheet distinguishes all three —
stale CSS, stale DOM, and a genuinely broken change — and **none of them are distinguishable from
each other in the viewport.** Every one of the three presents as "the change didn't work," and the
tempting response to each is to revert a change that was correct.
1. Computed-style probes (one `javascript` eval): a `.btn`'s `font-size` vs body; the phantom-token
replacement class resolving to real colors; the scoped bundle present in `document.styleSheets`.
**Measure behaviour rather than reading a computed value when the two can disagree.** Chrome