ripwire-reuse-first git:20260913.30a5a3cA

Immutable. This exact content is served forever at /api/v1/blob/9ee43894bab9193b.

---
name: ripwire-reuse-first
description: >
  About to write ONE symbol (even a 'quick' one-liner) or add a dependency: reuse before you reinvent.
  Finds the building block that already exists, the house pattern to imitate, the duplicate you'd
  recreate, a vendored dependency. An interface or whole feature → before-you-build. One --exemplar or --grep call
  at most.
allowed-tools: Bash, Read
---

# Reuse before you write

> Routing — pick the right door:
> • Starting a whole FEATURE (multi-symbol, needs a plan / interface / sizing) → **ripwire-before-you-build**.
> • The cross-cutting *map-before-you-read* token discipline for any read → **ripwire-orient** (`map-before-you-read.md`).
> • Judging whether what you wrote got better or worse before "done" → **ripwire-quality-bar**.
> • Not sure which skill? → **ripwire-router**.

The cheapest, simplest, most readable code is the code you don't write. Before authoring anything
non-trivial, spend one `ripwire` call (on PATH) to find what already exists.

## Retrieve by ROLE, never by raw similarity
This is the load-bearing rule, not a style preference: **similarity-retrieved "here's similar code, paste
it" measurably HURTS** — up to **−15% Pass@1** (arXiv:2503.20589). What
helps is API/type-signature context (+17-20%) and dependency-graph-structured retrieval (+6 EM; enabled 5/6
multi-file edits vs 0/6 without a graph). ripwire's shape — signatures + call-graph + role-ranked exemplars —
is the validated retrieval shape; "find me a similar-looking snippet" is the anti-pattern to avoid, even
though it's the tempting first instinct.

## Before you write a function / class / util
1. **Find the building block first** — `ripwire <dir> --for="<what you're about to build>"` → ranked existing
   signatures (plus, when the code has them, the `<lego>` / `<compose>` HAS-A blocks — what a class already
   owns). If you can name the helper you suspect exists, query it verbatim (`--for="parseByteSize"`) — `--for`
   auto-routes to name-exact retrieval and lands it at recall@1 ~99%. It also carries
   the quality lens (`cx`/`ccx`/`in`/`churn`/`amp`/`tested`) so you see which
   candidates are safe to extend. Often the thing exists — compose from it.
2. **Optionally get a style/shape exemplar** — if the retrieval result leaves a local-idiom question,
   `ripwire <dir> --exemplar=fn|method|class|struct|iface|var --legend=compact` (a kind) or
   `--exemplar="<task in words>"` (the top match's kind is inferred) returns the repo's single best-in-class
   instance of that shape: highest fan-in, lowest cognitive complexity, `tested=1` where possible — selected
   by ROLE, **not** text similarity. It returns the full body under `<bodies>`. **Copy its shape (structure,
   error handling, naming), not its text** — it is a model to imitate, not a relevant-code search.
3. **Find candidates by behavior/shape** — `ripwire <dir> --grep="<a word from the behavior>" --legend=compact`, or a NARROWED
   graph query: `--graph-query='and(file(all,"<area>"),kind(all,fn))'`. (Bare `kind(all,fn)` is ranked by
   importance + capped at `--top-k`, so it's safe — but narrowing by `file()`/`name()`/`callers()` finds the
   *relevant* building block, not just the globally-important one.) → implementations to reuse or extend.
4. **Don't duplicate** — `ripwire <dir> --clones --legend=compact` → if your intended body matches an existing one, call it
   instead. **Rule of Three:** extract a shared helper on the *third* occurrence, not the second — and prefer
   a little duplication over the *wrong* abstraction (a helper you bend with boolean flags is worse than two
   honest copies).

## Before you add a dependency
5. **Is it already here?** — `ripwire <dir> --external-surface --legend=compact` (what the tree already depends on; the default is a
   100-row window with the sh builtins dropped and counted as `builtins_excluded=` — `--include-builtins` keeps them) and
   `--uses=NAME` (the import role). Reuse an in-tree dependency before adding a new one: a new dep is build
   weight, supply-chain surface, and one more thing every reader must learn — it has to earn its place.
6. **Before adding/vendoring a NEW dependency, map the candidate repo first** — `ripwire <git-url>` (https://
   or git@; shallow-clones to a temp cache dir, then maps it like any local tree — `--refetch` forces a fresh
   clone instead of reusing the cached one). Run `--report`/`--hotspots`/`--deps` on it before you commit to
   the dependency: is it actually small and well-factored, or a god-file waiting to become your problem?

## When you do write
- **Match the local idiom** — `ripwire <dir> --for="<the area>"` shows the surrounding naming, layout, and
  error-handling style. Mirror it so your diff reads like the file, not like a graft (cache-friendly for the
  reader and for KV-cache reuse).
- **Less code wins on every metric at once:** lower complexity, fewer call edges, smaller blast radius, less
  to test, less to read. When in doubt, delete a parameter before adding one.

Then hand off to **`ripwire-quality-bar`** before you call it done.