ripwire-reuse-first · diff

git:20260905.2395543 to git:20260907.9e1e9f9

4 added, 10 removed. Audit A to A.

---

name: ripwire-reuse-first

description: >

- About to write ONE symbol — a single function, class, helper, or utility — reuse before you reinvent. Use

- the moment you're about to author any named thing (even a "quick" one-liner: duplicates are born on tasks

- that feel too small to tool up for), and before adding a dependency. ripwire finds the existing building

- block, the repo's best-in-class exemplar to imitate (by ROLE, not text similarity), the duplicate you are

- about to recreate, and whether the dependency is already in the tree, so you compose instead of reinvent.

- The least code is the least complexity, the fewest bugs, the smallest review, and the most cache-friendly

- diff. For a whole multi-symbol FEATURE (plan/interface/sizing) → ripwire-before-you-build. One

- --exemplar (or --grep) call at most — and if the fix is a one-line edit to an existing symbol, or the

- ranked output already showed the building block, skip this skill (and this file) and just write it.

- Backed by ripwire (deterministic, on PATH).

+ 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. A 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-efficient**.

> • 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,

`--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>"`, 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` → 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` (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.