/ripwire-orient

name: ripwire-orient
description: >
  Landing COLD in an unfamiliar repo or subsystem, or about to open several files for one question:
  map first, read only what it ranks highest — main subsystems, entry points, 'how does X work /
  where is Y'. Also recover context after compaction, retrieve saved docs (--recall), divide code for
  subagents (--partition), save gotchas (--note-add). NAMED symbol → navigate. Stop at the first rung
  that answers.
allowed-tools: Bash, Read

Orient with ripwire

> Routing — pick the right door: > • Tracing one call graph / locating a literal → **ripwire-navigate**. > • Vetting your OWN diff before you push → **ripwire-change-check**. > • Risk in code you did NOT write / an unfamiliar subsystem → **ripwire-fresh-eyes**. > • Map-before-you-read token discipline (any info need, mid-task) → this skill's companion **[`map-before-you-read.md`](map-before-you-read.md)** (folded in from the former `efficient` skill, 2026-09-07). > • Deep architecture-health read (deps metrics, layering rules, --arch gate) → **ripwire-layers**. > • Not sure which skill? → **ripwire-router**.

`ripwire` is on your PATH. First call on a tree parses (~1s even at 1500 files); every call after is warm (auto-cached, ~instant), so chaining several rungs is nearly free. `<dir>` = the repo root or the specific subsystem you're working in — also accepts a remote `ripwire <git-url>` (shallow-clones to a temp cache, so you can orient in a dependency before ever cloning it) — or several roots for a split checkout, `ripwire dir1 dir2 --report`: ONE merged, root-labeled map instead of two separate mental models.

**Orient ONCE per session, then look up lean.** Plain `ripwire <dir>` is the one-call orient: the ranked map with the subsystems, the program entries and every file the ranking left out (`<inv>`). Only that call carries `<inv>`: a `--for`, `--expand` or `--max-tokens` map does not, and `--max-tokens` drops the tier (use `--top-k` to keep it). After it, `--expand` / `--outline` / `--whereis` / `--callers` answer with no ride-along map. If you skipped the orient step, the `map_next=` on an `--expand` root is the call that prints it.

The escalation ladder — climb only until you feel oriented

**0. Recall what you already KNOW** — `ripwire <dir> --recall="<the task>"` The most relevant DOCS' FULL bodies (docs only, so code never swamps them — markdown memory notes, planning/design docs, skills, READMEs, plus `.ipynb`/`.html`/`.csv`/Office/PDF via the optional markitdown bridge). Point it at the **memory dir** for what past sessions learned, or the **repo root** for plans/designs — ~47× fewer tokens than loading everything. A design doc may already answer the question; if so, stop here. It also works unmodified as a zero-setup knowledge base over a scratch dir of dumped tool output (a git log, fetched docs, `--help` text) — not just a source repo. Two conditions are yours to meet when you WRITE the dump: dump it as `.md` (`.txt`/`.log`/`.json` are not documents to `--recall`, and a dir of them answers `0 relevant of 0 document files`), and keep `##` headings in it, so a deep answer is served as a ranked section instead of waiting behind a front-first cut. Raising `--max-tokens` then grows what ONE already-served document gets — that per-document guarantee is not global: dump several documents into one dir and admitting another one re-divides the shared budget, which can shrink an already-served document's own slice (`share_bytes=` in the header discloses it). Full form in [`map-before-you-read.md`](map-before-you-read.md); the recorded run is `docs/COMMANDS.md`'s `--recall` pattern subsection.

**1. Architecture summary** — `ripwire <dir> --report` Plain markdown: file + symbol count, call-graph modules (Louvain clusters with lead symbol), god-files ranked by `afferent` (dependents), cycle list, top PageRank symbols. **Read the god-file list carefully** — highest-leverage, highest-risk files. For most "orient me" asks this one rung is enough.

**2. Task-relevant code** — `ripwire <dir> --for="<the task in your own words>"` Ranked signatures + doc-comments + cx/in metrics by relevance (matches names, docs, AND bodies — not just identifiers). This is the rung that answers "where's the code for X". **What the bundle serves depends on which way the query routed, and the root says which.** *Named a symbol* (`bundle="auto" bodies="N"`): the anchor's FULL body rides inline, CDATA plus callee signatures — **read it here instead of opening the file the map named**, that follow-up read is the cost this default deletes. `bodies="0" reason="budget"` means it did not fit whole. *Conceptual phrase* (`bundle="compact" bodies="0" reason="compact-route"`): no bodies — you get the ranked map plus a `<hops>` section, one row per top-ranked symbol with its one-hop callee names. **Read the map, pick ONE symbol, then `--expand=path:name`** (paste the row's own `p=` and `n=`; a bare name that is not unique serves every definition, still without the map). That is the flow, and it is cheaper than the bodies were: half the bytes of the old bundle on conceptual queries, and the edges tell you which symbol is worth the second call. `--auto-bodies` restores inline bodies on that route if you want them; `--signatures-only` drops both shapes; `--detail=N` picks the body count explicitly. **Composing a selector out of a row** (the map's rows and `--for`'s alike): a scoped row carries `sc=`, its enclosing scope, instead of repeating its whole id — the canonical id is `p::sc::n`, assembled from the row's own `p=` (or the `<f p=>` it sits under), `sc=` and `n=`. Every selector (`--expand`, `--callers`, `--impact`, `--uses`) accepts that composed `path::scope::name`, so paste the three parts, not a bare name. `--for` **auto-routes** (default, no flag needed): a query that *names a symbol* (`--for="buildGraph"`) gets name-exact BM25 (recall@1 ~99% vs ~77% generic) — **know the name, query it verbatim**; a concept