Motir

Filed by motir run MOTIR-2957, per run.md's a bug card's FIRST deliverable is the REPRODUCTION rule (step 3 — a falsified premise is reported and the card amended on the record, never silently re-scoped). The correction is already applied; nothing is blocked on this card. Lesson: notes.html #306.

The defective card, AS AUTHORED

MOTIR-2957, quoted verbatim before the amendment (the tenant keeps no prior descriptionMd, so this is the record):

Title: status-derivation.spec.ts FLAKES on main — the 30s derivation poll loses under load, and the failure rotates between the UPWARD and DOWNWARD tests

Both failing tests poll db.workItem.findUnique(...).status for up to 30 s while the status-derivation/transitioned Inngest job derives the row. The executor log confirms the job DOES fire ("function":"status-derivation/transitioned", 31 initializations in a local run) — it simply has not landed the row inside the budget.

Wall-clock tracks it exactly: a green run of the file takes 18–40 s, a red one 48 s–1.3 m. The budget is what is being lost, not the logic.

2. Then decide between the two honest repairs, not both: raise the poll budget for the multi-hop assertions (cheap, and truthful if the work really is that slow), or remove the serial dependency so one derived status does not wait on the whole chain.

What the measurement found instead

The executor was IDLE for the whole 30 s. Every run of every work-item/transitioned consumer completed in ~350 ms, and no event had been published for 34 s by the time the poll gave up. The derivation was not late — it was cancelled, by rung 4 (MOTIR-2888): a work-item/created recompute for a child created moments before its parent was set Done pulled the parent back to todo, and the cascade's re-read of that row then declined. Controlled probe on origin/main @ a09c21ee: 7 of 20 trees settled at todo/todo/todo, terminal — a data-losing product race, not a slow test. Fixed in the same PR by taking §4's trigger off the transition instead of the row.

The two defects in the card

1. The mechanism is asserted in the TITLE and the body, on evidence that cannot support it. "A green run takes 18–40 s, a red one 48 s–1.3 m" — a red run is necessarily ~30 s longer, because a red run is one that spent the whole timeout waiting. The gap IS the timeout's duration, and it reads identically whether the work was slow or never happened. Likewise "31 initializations" proves the job fired; the question was whether it fired and declined, which a count cannot answer and the executor's run outputs can.
2. It enumerates the permitted repairs — "decide between the two honest repairs, not both" — and both presuppose the mechanism, so the menu steers the next run past the only question that mattered (did the derivation run at all?). The card's own first criterion ("the root cause is stated with a measurement … before any constant moves") is a good one, and sat one line above a menu that made it feel already satisfied.

The rule this argues for

A bug card's authority stops at what was observed. The mechanism is the next run's deliverable — put it in a Hypothesis section with the observation that would falsify it, never in the title and never as a menu of allowed fixes. Structural tell, cheap to check: a card that both DEMANDS a measurement and PRESCRIBES the repair has answered the question it is asking; one of the two is decoration, and it is always the measurement that gets skipped.

Worth noting against the usual reading of this class: the card was researched unusually well — it reproduced on a clean origin/main worktree, which is exactly the step the flake-classification rule exists to demand and which most cards skip. The diligence is what made the wrong diagnosis credible. A card saying only "this spec flakes; here is the reproduction; find out why" would have been weaker on the page and stronger in the hands of whoever ran it.

Deliverable

The lesson, notes.html #306 — this card's whole remaining scope. It stays a LESSON rather than a plan-rules/ change: one occurrence, and the RULES tier moves only when a pattern recurs (plan-rules/CORPUS-MAINTENANCE.md). A second instance of a card prescribing its own repair is what would promote it.