ripwire-router

# ripwire router — the moment → skill map Agents route by **moment**, not by feature. Find the row that matches what you're about to do; it names the ONE skill to enter. If you routed wrong, each skill's own routing header sends you one hop to the right one. ## Not sure which verb fits? Ask the tool itself `ripwire <dir> --help-task="<the task in words>" --legend=compact` returns ONE recommended command with the evidence behind the pick (intent, score/margin, repository facts) — or honestly abstains when the evidence is too thin to name a winner. One hop cheaper than reading this whole map: paste the task, run what it recommends. Advice only — it never executes the recommendation. | The moment you're in | The ONE skill | Its opening move | |---|---|---| | **Cold-start** — landed in an unfamiliar repo, "what is this / what matters here" | **ripwire-orient** | `--recall` then `--report` | | **Resuming after a context compaction / a new session on work already in flight** — you have a task but no longer the reasoning that got you here | **ripwire-orient** | rebuild state instead of re-reading files: `--recall="<the task>"` (what past sessions WROTE down) → `--situ` (what the working tree currently has changed + tests to run) → `--notes` (gotchas already paid for). Cheaper and more accurate than re-deriving from source. | | **A pile of DUMPED output, not code** — a `git log`, fetched docs, `<tool> --help`, one oversized reference file, and you need ONE answer out of it | **ripwire-orient** | point `--recall` at the dump directory itself: `ripwire <dumpdir> --recall="<the question>"` — a zero-setup knowledge base, nothing to install and no daemon (one cold parse, warm after). Two rules decide whether it works at all: **dump to `.md`** — `.txt`/`.log`/`.json` are not documents to `--recall` and it answers `0 relevant of 0 document files` — and keep `##` headings in the dump, because a headed document is served as whole ranked SECTIONS (the served `[sections: …; lines="…"; dropped_by_budget=D]` note discloses the cut) while a headless one is still cut front-first. | | **Understand X** — "how does X work / where is Y / architecture overview" | **ripwire-orient** | `--for="X"` | | **Trace one symbol** — who calls it, what it calls, is it safe to change, locate a literal | **ripwire-navigate** | `--callers`/`--callees`/`--impact`/`--grep` | | **Find an exact literal** — error text, config key, or emitted string | **ripwire-navigate** | `--grep='literal' --grep-context=2`; add `--and`/`--not`, `--grep-scope=file`, or `--grep-in=any` only when the first answer requires it | | **Verify one closed code claim** — does A call B, is X unused, does a file define/contain Y? | **ripwire-navigate** | `--verify='calls(A,B)'` (also `uses`/`unused`/`contains`/`defines`/`reaches`) | | **My task touches A, B and C — how do they relate?** — N (>2) task symbols, or a pair `--path` can't reach | **ripwire-navigate** | `--connect=A,B,C` (the shared-caller join a directed `--path` can't see) | | **Planning a FEATURE** — multi-symbol work needing a plan / interface / size estimate | **ripwire-before-you-build** | `--recall` + `--for` + `--seams` | | **Implementing against an interface** — writing a class/type that must satisfy interface `I` | **ripwire-before-you-build** | `--lego=I` (I's method contract + every existing implementor to copy) | | **About to write ONE symbol** — a fn/class/helper, even a "quick" one | **ripwire-reuse-first** | `--exemplar` + `--for` + `--clones` | | **Mid-implementation** — about to open several files just to learn something | **ripwire-orient** (`map-before-you-read.md`) | cheapest verb, then read 2-3 files | | **Reviewing MY diff** — "am I ready to push / is this safe to merge" | **ripwire-change-check** | `--quality-delta` (that's the quality-bar reflex) → `--pr-context` | | **Which tests should I run for this change? Did I run the right ones?** | **ripwire-change-check** | `--affected=F1,F2` / `--situ` → `--test-gate` | | **A test failed and I have its name and nothing else** — what does this harness actually cover? | **ripwire-change-check** | `--exercises=TESTFILE` — the INVERSE of `--affected`: the non-test symbols this test transitively calls into | | **My symbol is missing from the map** — expected a def to show up and it didn't | **ripwire-orient** | `--skipped` first (was its FILE dropped — a size ceiling, one row per oversize file); if the file isn't oversize-skipped, `--doctor` next (stale binary, grammar/parse failure, cache-dir health — a setup check, not a bug report) | | **Writing tests for existing (untested) code** | **ripwire-write-tests** | `--seams` + `tested=1` coverage lens + `--callers=SYM` | | **Reviewing code I did NOT write** — unfamiliar subsystem, "what's gnarly here" | **ripwire-fresh-eyes** | `--quality-panel` (THE SINGLE COMMAND — six evidence families in one ranked report; a lens, not a gate) — or `--hotspots` + `--clones` + `--owners` one lens at a time (scope to the subsystem) | | **Debugging** — a symptom, a suspect subsystem, or "I changed X and it broke" | **ripwire-find-bug** | `--for=symptom` / `--situ` | | **I HAVE a stack trace / sanitizer report / compiler error** — paste it, don't hand-translate it | **ripwire-find-bug** | `--from-trace=FILE` (or `-` from stdin) — frames → ranked in-corpus suspects, innermost first | | **Just edited a symbol** — "did I change a contract someone depends on?" (pre-commit, per-symbol) | **ripwire-change-check** | `--edit-check=SYM` — unchanged / new-symbol / contract-change + flagged incompatible callers, ~26 ms warm | | **Apply a whole-symbol edit** — replace a definition or insert beside one without a whole-file Read | **ripwire-orient** (`map-before-you-read.md`) | CLI first: `--replace-symbol-body=SYM --edit-payload=FILE|-` (or `--insert-before-symbol` / `--insert-after-symbol`); add `--edit-target-file=PATH` only for ambiguity. MCP has same-named warm-server counterparts. | | **Landing several branches / parallel agent worktrees** — who conflicts, what order? | **ripwire-change-check** | `--merge-scout=REF1,REF2,…` — pairwise conflict sites + a suggested landing order | | **Branch/content archaeology** — "I have 30 branches and don't know what's stranded on them" (not a diff review) | **ripwire-change-check** | `--stray-content[=SUBSTR]` (unmerged/superseded/merged verdict per ref) + `--whereis=SYM` (which ref defines/mentions it) | | **Worth remembering for the next session** — a gotcha tied to a symbol/file (trap, flake, invariant) | **ripwire-orient** | `--note-add="SYM: text"` — surfaces automatically whenever `--for`/`--expand` later emit that symbol | | **One-call orientation under a budget** — the whole --for → bodies → callers → tests dance at once | **ripwire-orient** | `--pack-task="task"` (+ `--token-budget=N`) — ranking, top bodies, caller sigs, notes, tests_to_run in ONE bundle | | **About to FAN OUT** — spawning N subagents / worktrees / lanes, about to hand-write N per-agent briefs | **ripwire-orient** (`map-before-you-read.md`) | `--pack-task="task" --partition=N` (N=2..16) — ONE shared core plus N minimally-overlapping slices carved along the call graph's own communities, so N agents stop re-deriving the same orientation. `--token-budget` here means ONE agent's budget; each inner `<ctx>` is byte-identical to that agent's standalone call, so hand it over verbatim. Check `overlap_max` before trusting the split, and `split="K"` (>0 = a module was cut at its rank median because there were fewer modules than agents). Then `--plan-lanes=N --task="…"` (or `--plan-lanes --brief=FILE`) for the conflict-aware version: which lanes would COLLIDE, in what order they should land, and what each must test — JSON, pre-hoc, before a line is written. | | **Refactoring** — planning a restructure, or a suspected god object | **ripwire-fresh-eyes** | `--communities`/`--metrics` (lcom4) + `--impact` + `--cochange`; read the nesting PROFILE (`humps=`/`deep=`), never `nest=` alone | | **I have the measurement — now WHICH refactor, and is it safe?** — a shape (many shallow humps / one deep tangle / small-and-dense / untested hub / a clone) needs a named fix and its precondition | **ripwire-quality-bar** | the shape → refactor playbook, then the closed fix loop: `--quality-delta` → `--edit-check=SYM` → `--affected` | | **Perf** — a benchmark/profile (including a flame graph) identifies a slow operation or symbol | **ripwire-perf-target** | measure → navigate measured surface → re-measure; if the counters say MEMORY not compute, `--field-affinity[=STRUCT]` (a hypothesis generator, never a measurement) | | **A clang optimization remark while editing ripwire's OWN C++** — `-Rpass`/`-Rpass-missed` says "loop not vectorized" / "will not inline" / etc, and you need to decide if it's worth a diff | **ripwire-opt-remarks** | `scripts/optremarks.sh` then `scripts/optremarks.py --hot` — contributor-facing, not a general perf-investigation entry: a generic "this is slow" / "where's the bottleneck" prompt with no remark in hand is **ripwire-perf-target**, not this | | **Security** — untrusted input, reviewing security-sensitive code, or auditing a skill/MCP config | **ripwire-security-scan** | `--lint` unsafe fns + `--scan-skills` | | **Handoff** — writing a summary of a repo/change for the next agent or teammate | **ripwire-handoff** | the handoff bundle | | **What's built but DARK here** — "why don't I see feature X" (code compiled/flagged OFF, not a bug) | **ripwire-fresh-eyes** | `--flags[=SUBSTR]` (dark-gate dashboard) + `--flip=NAME` (blast radius of turning one ON) — **ripwire-find-bug** points here too when a symptom turns out to be a dark flag | | **Task spans multiple checkouts** — service+client, a split monorepo — one question over BOTH | any moment skill above | pass every root: `ripwire dir1 dir2 --for=…` (one merged graph; `--impact` across roots needs the workspace call). Refusal boundary: `--quality-delta`/`--test-gate`/`--eval*`/`--arch --baseline` stay single-root (HEAD-keyed baselines and corpora are per-repo) — run those per root. | | **Is my ripwire setup healthy / am I running a stale binary?** | (no skill — run directly) | `ripwire <dir> --doctor --legend=compact` — binary-vs-PATH staleness, grammar compile, cache-dir health, git reachability (single-root, diagnostic not deterministic) | ## You are not in a "moment" — you are about to reach for a default The table above assumes you recognized a moment. The most expensive case is the one where you did not: you simply went for `Read`, `Grep`, or `Glob` because they are always there. That reflex needs no recognition and no skill load, which is exactly why it wins by default and why it costs the most. Match the **default you were about to use**, not a moment: | About to… | Reach for instead | |---|---| | `Read` a whole file to understand one function | `--expand=SYM` — that symbol's body + its callees' signatures. The file is not the unit of an answer. | | `Read` several files to learn how something works | `--pack-task="<task>"` — ranking + bodies + callers + tests in ONE budgeted call | | `Grep`/`rg` a symbol name across the tree | `--for="theExactName"` (name-exact routing, recall@1 ~99%) · `--uses=SYM` for every read/write/import site | | `Grep` a concept ("where do we retry") | `--for="<the concept in words>"` — matches doc-comments and bodies, not just identifiers | | `Glob` for candidate files by name | `--for=` ranks by what the code DOES; a glob only knows paths | | paste a stack trace and hand-pick frames | `--from-trace=FILE` (`-` = stdin) — verbatim, ranked innermost-first | | `git diff` / `git log` to judge a change | `--situ` (blast radius + tests) · `--rank-by=churn` | The discipline behind this row set is **ripwire-orient**'s companion `map-before-you-read.md`; it is worth entering even mid-task, because less context is measurably MORE accurate, not merely cheaper (29% → 3% code-repair accuracy as context grew 32K → 256K, LongCodeBench). If a `ripwire wrap` primer or the opt-in `skills/install.sh --hook` nudge is installed, these same substitutions arrive without anyone loading this file — that is the point: a rule an agent must remember to look up is a rule that loses to a habit. ## The legend: compact by default, full when a definition needs its reasoning Every command these skills spell asks for the compact legend (`--legend=compact`: terse definitions of only the attributes the answer carries). Add `--legend=full` when a definition's reasoning is needed — a term you do not recognise, a floor or cap you need explained, or a map a human will read. `--for` is the exception by CHOICE: its default legend is already the one to read first, and its compact legend is its own. The other exceptions are not a choice — **the binary refuses the flag on any command that does not answer with an XML legend**, and a command it refuses runs not at all. Two families: the **state-changing** commands, which write something rather than answer (`--quality-ack`, `--quality-baseline`, `--arch --baseline`, `--note-add`, `--replace-symbol-body` / `--insert-before-symbol` / `--insert-after-symbol`, `--edit-plan`, `--index-out=`, `--pin-census=`), and the **non-XML renderings** (`--mermaid`, `--html`, `--report`, `--sarif`, `--situ`, `--recall=`, `--export`). Those carry no `--legend=` at all. This matters when you compose rather than copy: a flag that turns an XML verb into one of these — `--zoom --mermaid`, `--quality-delta --quality-ack` — takes the whole command with it, so the verb is not what decides, the command is. Nothing here is a rule you have to apply by hand: `ripwire --help-task` applies it for you, and `test/skilltruthcheck.sh` runs every `--legend=compact` command these skills spell against the binary and fails on a refusal. ## Cross-cutting disciplines (fire ALONGSIDE a moment skill, not instead)