bvandeusen
dd1b5e5ddb
"What canonical helpers already live in this file?" was unanswerable: location lived only in the body markdown. It is now a jsonpath containment query over the `notes.data` mirror added by migration 0070. - One predicate in two dialects in services/knowledge.py: SQL (`data @?`, applied in the browse arm and the keyword arm before count/pagination, so totals stay honest) and Python (`location_matches`, for the semantic arm which post-filters candidates it already holds). Both must change together. - Parts are ANDed within a SINGLE locations entry — repo A in one entry and path B in another is not "recorded at A/B". `path` also matches as a directory prefix, via jsonpath `starts with` rather than `@>`, which the same GIN index serves. - `repo`/`path`/`symbol` reach the service, the REST list and the MCP tool under one name with one default (rule #33); the MCP docstring teaches the place form, and so does the reusing-code skill (plugin.json bumped). - UI: a Location disclosure beside the snippet search, with its own empty state — "nothing kept there, so what you're about to write is new." Settles #2083's open question (pre-0070 NULL `data`) by backfilling after all: `backfill_snippet_data` runs at startup, deriving the mirror from the body with the same parser the read path trusts. 0070's caution was about mangling a hand-edited body; this never touches the body. The alternative was a permanent second body-regex arm, or a query that silently answers "nothing here" for an old snippet and gets the helper written twice. Refs #2083, milestone #232.
5.3 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. - About to edit an existing file? Ask by place, not just by meaning.
list_snippets(repo="…", path="…")answers "what canonical helpers are already recorded here?" —pathmatches the exact file or anything beneath it, sopath="frontend/src"covers the whole tree. Cheaper and sharper than a wording search when you already know where the code is going, and it catches the helper you'd otherwise duplicate a few lines down.symbol="…"narrows further, and all three must match the same recorded location. Combine withqto ask both at once. - 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).
A shared snippet is a suggestion, not a standard
Scribe is multi-user, so a search can return snippets other people own. Those
come back marked shared: true with an owner.
- Read one as that person's suggestion, not as the way things are done here. Judge the code on its merits before reaching for it.
- Say whose it is when you propose it — "there's a snippet from alex that does this" — so the operator can weigh the source, not just the code.
- Don't treat it as the house pattern, and don't build on it at scale, without the operator agreeing to adopt it.
- Snippets shared directly with the operator only appear when you search for
them, never in a plain
list_snippets— so anything ambient is genuinely theirs.
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.