FabledScribe/plugin/skills/using-scribe/missed-retrieval.md

When a record doesn't reach the moment it should

Part of the using-scribe skill. Read it when a rule should have governed a moment and never arrived, when one arrives on every turn and never applies, or before touching a retrieval floor.

Retrieval misjudging is ordinary, and it is fixable — but only by whoever notices. Either direction counts: a rule that should have governed a moment and never arrived, and a rule that arrives on every turn and never applies. So does either noticer: the operator saying "that should have fired", and you noticing it yourself — you reached for a rule nobody offered you, or you were handed the same rule five times and set it aside five times.

First ask whether it missed a WHEN or a WHAT. A rule about a point in the work — it governs delivering, finishing, verifying, reporting, whatever the work is about — is not a trigger to reword: no wording resembles every piece of work that reaches that point. Mount it on the moment instead (update_rule(moments=[...]), from list_moments); a mount is a lookup, and it arrives every time the moment happens. When it is already mounted and still did not arrive, the action did not reach the moment on this install — offer map_action for that action. The reverse — a mounted rule arriving where it does not apply — is a mount or a mapping that is wrong: take the moment off the rule, or unmap_action the action that reached it. Each of these changes what the operator's sessions receive, so offer it in one line and make it on their yes. When it is not plain enough to offer yet, rule_misfired records it, and repeated reports become the offer. The skill's moments reference has the detail. A rule about a subject missed its WHAT, and the rest of this page is for that.

Take it to the record first and the dial second. A rule's when_to_apply IS the text its similarity score is computed against, so when a rule misses a moment it governs, the overwhelmingly likely cause is that its trigger does not describe that moment in the words a session actually produces. Rewording one trigger changes one rule's reach. Moving a floor changes what every record on that surface does, and a floor cannot tell a badly-worded trigger from a genuinely distant record — so one lowered to rescue a single rule admits everything else that was sitting in the same band.

1. Read the refused records. retrieval_telemetry(days=N, near_miss_samples=5) names by id what each surface refused and by how much. Open them with get_rule / get_note. This is the step that carries the answer: the statistic says a record was close, and only the record says whether it was right.

2. Fix the trigger. update_rule(when_to_apply=...), written as the symptom — what the session was doing or saying at the moment it needed this rule — not the situation the rule belongs to. Then check that it worked: what_might_apply("the moment, in the operator's own words") and read where the rule now ranks. The change is measurable, so measure it, and say the before and after when you report it.

3. Then consider the dial. retrieval_surfaces shows what is in force per arm and whether the number is still calibrated; tune_retrieval moves it. reason is required and has to say what you read, because it is what lets the operator disagree with a number they did not choose.

   A budget is judged by what sits past it, and an open rate cannot judge it. Every menu line carries its matched passage, so a record left unopened may have been unrelated, enough as shown, or already in context. menus_to_review re-runs a sample of logged menus to a depth past the budget; judge each line from what is shown with judge_menu, then read retrieval_telemetry's judged block. If the lines past the cut are mostly on_point, the budget is costing hits; mostly unrelated, it is doing its job.

Reaching for tune_retrieval before opening a single record is the wrong move, and it is the one that feels efficient. Worked example, measured on this install: a rule granting a routine push scored 0.6515 and ranked 5th for the moment it governed, behind three rules that restrained the same act. Every percentile said "lower the floor" — and lowering it would have delivered those three restraints and still not the rule. Rewriting the trigger to lead with the symptom moved the same rule to 1st at 0.7130, ahead of all three. Only then was the floor worth touching.