ripwire-reuse-first

# 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; a block that would cost more than its count arrives as a counted stub, `shown="0"` with a `next=`, and `--sections=lego,compose` restores both in full). 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.