From 20e3731eb13b4d78aab2e524593582603a39faaf Mon Sep 17 00:00:00 2001 From: gsxdsm Date: Fri, 31 Jul 2026 01:17:19 -0700 Subject: [PATCH] docs(workflow-learnings): a deferral's stated blocker is a claim, and it decays like a measurement (#3026) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two pieces of work were filed rather than fixed in one session, each with a specific technical reason. **Both reasons were wrong**, and in both cases the real obstacle was smaller than the stated one. | filed rationale | reality | |---|---| | "the plugin has no scaffolding for faking its stores" (#3020) | `_harness.ts` builds a real `PluginContext` over a live PostgreSQL layer; the gap was **two missing readers on a stub** — fixed in #3022 | | "supplying this needs a published-API change" (#3003) | the type is dashboard-internal, `@fusion/plugin-sdk` is `private: true`; the actual obstacle is stale type declarations between two in-repo packages | The first one matters most: the filed issue was a **pipeline that stalls forever** on a renamed board. The cost of that excuse would have been a real stall sitting open behind a plausible-sounding note. ## The shape Both times the blocker was asserted **from the shape of the problem** rather than tested. *"This needs infrastructure that doesn't exist"* and *"this crosses a published boundary"* are each checkable in about five minutes, and neither was checked before I wrote a paragraph explaining why the work couldn't proceed. ## Why it's worth writing down Filing is often right — someone else owns the contract, the fix needs a decision, the data genuinely isn't there. What makes it wrong is filing on an **untested** blocker, because a filed issue with a confident rationale is the one thing nobody re-derives. It reads as settled. That's the same mechanism as a stale "do not re-probe" note (which this document already records, and which I had to correct in #3018), one level up: there a *measurement* went stale, here a *decision* did. ## The rule **Before writing the blocker down, spend five minutes trying to hit it.** If it's real you'll hit it immediately and can describe it precisely — which makes the issue more useful. If it isn't, you have the fix instead of the issue. Docs only. No code, no baselines. Co-authored-by: Claude Opus 5 (1M context) --- ...ifecycle-conversions-that-score-as-wins.md | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/solutions/workflow-learnings/lifecycle-conversions-that-score-as-wins.md b/docs/solutions/workflow-learnings/lifecycle-conversions-that-score-as-wins.md index 3ecd68714e..2eb3844783 100644 --- a/docs/solutions/workflow-learnings/lifecycle-conversions-that-score-as-wins.md +++ b/docs/solutions/workflow-learnings/lifecycle-conversions-that-score-as-wins.md @@ -343,6 +343,35 @@ tool and a bad ratchet; the distinction is worth keeping. The triage that does work is cheap: run the scan, then for each hit ask the two questions above. Nine of the nineteen survive question 1; hand-checking those is an afternoon, not a project. +### A deferral's stated blocker is a claim, and it decays the same way a measurement does + +Two pieces of work were filed rather than fixed in one session, each with a specific technical reason. +Both reasons were wrong, and in both cases the real obstacle was smaller than the stated one. + +- **"The plugin has no scaffolding for faking its stores."** It had `_harness.ts`, building a real + `PluginContext` over a live PostgreSQL layer. The gap was two missing readers on a stub — additive, + and inert for every existing suite. The filed issue was a pipeline that stalls forever on a renamed + board, so the cost of that excuse was a real stall sitting open behind a plausible-sounding note. +- **"Supplying this needs a published-API change."** The type was dashboard-internal and the SDK + package is `private: true`. Every consumer was in-repo. Building the chain took minutes and + surfaced a different, smaller obstacle: the plugin compiles against stale dashboard type + declarations, which is build plumbing rather than an API decision. + +The shape is the same both times: **the blocker was asserted from the shape of the problem rather than +tested.** "This needs infrastructure that does not exist" and "this crosses a published boundary" are +both checkable in about five minutes, and neither was checked before writing a paragraph explaining +why the work could not proceed. + +Filing is often right — someone else owns the contract, the fix needs a decision, the data genuinely +is not there. What makes it wrong is filing on an *untested* blocker, because a filed issue with a +confident rationale is the one thing nobody re-derives. It reads as settled. That is the same +mechanism as a stale "do not re-probe" note, one level up: there a measurement went stale, here a +decision did. + +The rule that costs nothing: **before writing the blocker down, spend five minutes trying to hit it.** +If it is real you will hit it immediately and can describe it precisely, which makes the issue more +useful. If it is not, you have the fix instead of the issue. + ### The probe harness lies more often than the gate does Probing four gates with unimagined shapes in one session produced **two rounds of silently invalid