bvandeusenandClaude Opus 5.5
d5dad587f1
CI & Build / Python lint (push) Successful in 4s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / TypeScript typecheck (push) Successful in 55s
CI & Build / integration (push) Successful in 1m8s
CI & Build / Python tests (push) Successful in 1m44s
CI & Build / Build & push image (push) Successful in 21s
Anthropic's skill guidance: keep SKILL.md under 500 lines, split into reference files linked one level deep as it nears that. using-scribe was 478 and every new practice lands there. - SKILL.md 478 -> 317 lines. It keeps orientation, one copy, the reflexes, scope, the judge section, UI and the process-skill index, plus a "Read these when the moment comes" list naming each file with its moment. - projects.md: binding a non-git directory (.scribe) and project inception. - writing-records.md: where a new rule goes, lesson growth, and notes that carry their own check (reflex 10 keeps a pointer). - missed-retrieval.md: the record-before-dial route, verbatim. - Text moved, not rewritten, except for the seams and one cross-reference. Tests: - tests.helpers.skill_text reads SKILL.md plus its reference files. The ownership registry, the miss-route and the verification tests use it, so a topic stays owned by its skill whichever file holds it. - The force test scans every skill .md on its own, since each file is read on its own. - New test_skill_structure: SKILL.md <= 350 lines, every reference file is linked from SKILL.md, none links another, and one over 100 lines opens with Contents. Each guard is shown to fail. The plugin version is minted. That also clears 4fb53b8's red Plugin hooks lane, which failed only because PACKAGING.md changed without a mint. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
47 lines
2.8 KiB
Markdown
47 lines
2.8 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.
|
|
|
|
**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.
|
|
|
|
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.
|