bvandeusenandClaude Opus 5.5
a72a422534
CI & Build / Python lint (push) Successful in 13s
CI & Build / Plugin hooks (push) Successful in 16s
CI & Build / TypeScript typecheck (push) Successful in 56s
CI & Build / integration (push) Successful in 1m38s
CI & Build / Python tests (push) Failing after 1m59s
CI & Build / Build & push image (push) Skipped
Until now only the tool arguments knew moments existed. The guidance surfaces described rules as reached by resemblance alone: - using-scribe: a short reflex paragraph and a new reference file, moments.md. It covers reading "at <moment>, reached by <action>", the reply held once at reply.report, map_action / unmap_action offered in one line, and the step 7 proposal line answered with judge_rule_moments. - writing-records: asks WHEN a rule applies as well as what it is about. A rule, preference or process about a point in the work gets moments=[...] as it is written, and the trigger stays as the net. - missed-retrieval: a missed WHEN is mounted or mapped, not reworded. A misfire is unmounted or unmapped. - _INSTRUCTIONS: one clause (list_moments; mount rules about WHEN), 1594 of 1600 chars. - static context: injected lines include the rules mounted on a moment that was reached. - test_guidance_ownership: three owned topics, so the text cannot quietly drop out. Plugin minted. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
71 lines
4.3 KiB
Markdown
71 lines
4.3 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. [moments.md](moments.md) 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.
|