From 98da4ec1f12c367c27194e01c8dc5244ffce9500 Mon Sep 17 00:00:00 2001 From: Vuong Hoang Date: Wed, 9 Sep 2026 17:50:53 -0700 Subject: [PATCH] =?UTF-8?q?docs(ops-lessons):=20=C2=A711=20fourth=20varian?= =?UTF-8?q?t=20=E2=80=94=20the=20instrument=20read=20a=20surface=20mid-tra?= =?UTF-8?q?nsition?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From a near-miss brokkr-smithy-dev caught and declined to send: a post-fix verification read raced a gateway restart and reported the alias still present. A disagreement between two observers is not a finding until the boring explanation is ruled out, and during an incident the pressure runs the other way. --- docs/pfi/ops-lessons-playbook.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/pfi/ops-lessons-playbook.md b/docs/pfi/ops-lessons-playbook.md index 124459f..84ec6da 100644 --- a/docs/pfi/ops-lessons-playbook.md +++ b/docs/pfi/ops-lessons-playbook.md @@ -359,6 +359,27 @@ themselves: they waste attention and misdirect, but they cannot silently destroy a good artifact. A post-mortem that lumps all three together loses the half that decides what to do about it. +### A fourth variant: the instrument read a surface MID-TRANSITION + +Added 2026-09-09 from a near-miss brokkr-smithy-dev caught and did not send. +Verifying the `trial` alias removal, its first read returned 34 aliases with the +alias **still present** — which looked exactly like the fix had not taken. It +had. The read had raced the gateway restart. The tell was that the next three +reads came back non-JSON, because the service was mid-restart; waiting for it to +settle returned 33 and no alias. + +Had that first read been sent, it would have been a **false alarm during an +incident**, and the cost is specific: the other party goes back to re-verify a +fix that was already correct, on the word of an observer who sampled a surface at +a moment nobody meant to ask about. The instrument answered honestly about the +wrong instant. + +**The rule: a disagreement between two observers is not a finding until the +boring explanation is ruled out** — a race, a restart, a cache, a stale read. +During an incident the pressure runs the other way, because a discrepancy feels +urgent and urgency argues for sending it immediately. Read twice, let the surface +settle, and prefer the explanation that requires nothing to be wrong. + **How to apply.** When you write or review a guard, open its writer in the same pass and state the contract out loud — `touch` → exists-but-empty; `mv` on exit-0 → may be empty; `>` → may be truncated; `pgrep -f ` → matches