bvandeusen
b33e2a79c6
Four defects from the 2026-07-25 review of the recall (#227) and merge (#231) milestones. The theme: a snippet could be recorded but not fully corrected, and the agent and web surfaces had drifted apart. - #2076 language was mis-derived from the first caller tag, so a snippet created with tags and no language read that tag back as its language — corrupting the tag set and the code fence on the next update. Only the FIRST tag can carry the language, since compose_tags emits [language, "snippet", *caller]. - #2077 MCP update_snippet mapped "" to "unchanged", so no field could ever be cleared and no snippet detached from its project. Now an omitted field is left alone, an empty string clears, and project_id follows the -1 = detach convention. A service-level UNSET sentinel keeps None available as the clear. - #2078 surface parity: adds delete_snippet (MCP had none, so a wrong snippet could not be retired by the agent that recorded it), locations on MCP create and update, system_ids through the REST routes and the editor, and the near-duplicate gate on REST create with a "record it anyway" escape. - #2079 project scoping: list_snippets takes project_id through the service, the MCP tool and the REST route, defaulting to every project — reaching across projects is the point when the helper you need was written elsewhere. Sharing the list across owners is deliberately NOT in here: query_knowledge is shared with the Knowledge browse surface, so widening it changes behaviour well beyond snippets. Left open on #2079 for a scope decision. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RLwAaV4DQEmVyn496HnEvt
4.0 KiB
name, description
| name | description |
|---|---|
| reusing-code | Use when you're about to write a helper, utility, hook, or reusable component — search recorded snippets FIRST so prior art is reused instead of re-solved. And the moment you build or notice something reusable, record it as a snippet so a later session finds it. Triggers on "write a util/helper", "I need a function that…", "let me add a component", or just having built something worth reusing. |
Reusing code — recall before you rebuild
Reusable code is worth writing once. Scribe stores snippets — a named, reusable function or component recorded with its language, signature, canonical location (repo · path · symbol), a one-line "when to reach for it," and the code itself — so prior art can surface before it's re-written as a one-off. Snippets are ordinary embedded notes, so a recorded one also surfaces on its own through recall/auto-inject; this skill is the active reflex around that.
Before you write a new helper — search first
- About to write a utility, hook, formatter, adapter, or a reusable component?
Search snippets before writing it.
list_snippets(q="…")(or a plainsearch) — a matching one may already exist, in this project or another.list_snippetssearches every project by default; that's deliberate, since a helper you need here was quite possibly written somewhere else. Narrow withproject_idonly when you specifically want this project's own. - If a snippet fits, pull it in full with
get_snippet(id)and reuse it — itslocationpoints at the reference implementation. Adapt, don't re-derive. - If auto-inject already surfaced a snippet title that looks relevant, that's
your cue to
get_snippetit rather than start from scratch.
The moment you build something reusable — record it
- Just wrote (or noticed) a helper, hook, pattern, or component worth repeating?
Record it with
create_snippetwhile it's fresh:- name — what it's called, e.g.
useDebouncedRef. - code — the implementation.
- when_to_use — one sharp line on when to reach for it. This becomes part of the title, so it's what a later recall menu shows — make it earn the pull.
- language, signature, and location (
repo/path/symbol) so the recorded copy points back at the canonical source. - project_id / system_ids to associate it with the work it belongs to.
- name — what it's called, e.g.
- Record the reference implementation, not every call site — one good entry
per reusable thing. If it already exists,
update_snippetit instead of recording a second copy (the create gate will flag a near-duplicate anyway).
Keep the record honest
A recorded snippet is offered as prior art on every matching turn, so a wrong one costs more than a missing one.
- Details gone stale — a renamed symbol, a moved file, a signature that's
changed? Fix it with
update_snippet. Passing an empty string clears a field, so a wrong signature or location can be removed, not just written over. - Recorded something that turned out not to be reusable, or that no longer
exists? Retire it with
delete_snippet— it goes to the trash and can be restored. Don't leave it competing for attention.
Found the same thing in several places — unify it
When you notice the same reusable thing recorded (or written) as several
one-offs, don't leave the duplicates competing in recall — merge them.
merge_snippets(canonical_id, [other_ids]) keeps one canonical record, folds in
the others' call sites as locations, and retires the duplicates to the trash.
The result is a single entry that shows every place the thing is used — which is
exactly the signal that it was worth consolidating. This is the cure the create
gate only hints at when it blocks a near-duplicate.
Why this pays off
A one-off written a second time is the cost this avoids. Recording a snippet once — with a location and a crisp "when to use" — means the next session is offered the prior art instead of re-solving it. Search before writing; record what's worth reusing.