bvandeusen
b33e2a79c6
CI & Build / Python lint (push) Successful in 3s
CI & Build / TypeScript typecheck (push) Successful in 11s
CI & Build / integration (push) Successful in 19s
CI & Build / Python tests (push) Successful in 43s
CI & Build / Build & push image (push) Successful in 1m7s
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
71 lines
4.0 KiB
Markdown
71 lines
4.0 KiB
Markdown
---
|
|
name: reusing-code
|
|
description: 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 plain
|
|
`search`) — a matching one may already exist, in this project or another.
|
|
`list_snippets` searches every project by default; that's deliberate, since a
|
|
helper you need here was quite possibly written somewhere else. Narrow with
|
|
`project_id` only when you specifically want this project's own.
|
|
- If a snippet fits, pull it in full with `get_snippet(id)` and reuse it — its
|
|
`location` points 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_snippet` it 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_snippet` while 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.
|
|
- Record the *reference* implementation, not every call site — one good entry
|
|
per reusable thing. If it already exists, `update_snippet` it 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.
|