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) <noreply@anthropic.com>
20e3731eb1