bvandeusenandClaude Opus 5.5
4e1320120d
CI & Build / Python lint (push) Successful in 2s
CI & Build / Plugin hooks (push) Successful in 16s
CI & Build / TypeScript typecheck (push) Successful in 54s
CI & Build / integration (push) Successful in 1m19s
CI & Build / Python tests (push) Successful in 2m3s
CI & Build / Build & push image (push) Successful in 18s
The open-after-moment signal proposes a mount; nothing proposed taking one off, so a wrong mount was noise at every occurrence until someone happened to notice. rule_misfired(rule_id, moment, why, reached_by) records a report against a MOUNTED pair, counted per distinct day (the MCP door carries no session id) on a new rule_moment_judgments.misfire column (migration 0119, backup v24). At three days the response carries a line asking the agent to offer the operator the fix - reject takes the rule off, unmap_action stops the action reaching the moment, confirm keeps the mount and stops the asking - and Settings > Moments lists it as an unmount proposal with the reasons and the actions that reached it. A re-mount clears the count. Taught in moments.md, missed-retrieval.md and the reply hold's wording. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
72 lines
4.4 KiB
Markdown
72 lines
4.4 KiB
Markdown
# 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.
|