/ripwire-perf-target

name: ripwire-perf-target
description: >
  A MEASURED performance problem: start from a benchmark, flame graph, perf sample or profiler run,
  locate the hot symbol the profile names, test structural hypotheses (memory-bound → cache-line data
  layout). Static metrics are change-risk signals, not runtime heat. Inspect only the symbols the
  profile names.
allowed-tools: Bash, Read

Performance targeting with ripwire

> Nearest neighbours: > • Repo-wide quality/health sweep (not perf-specific) → **ripwire-fresh-eyes** (also uses --hotspots). > • Finding a specific BUG, not a slow path → **ripwire-find-bug**.

Trigger: a representative benchmark, flame graph, trace, or profiler has identified a slow operation, file, stack, or symbol and you need to understand where a safe optimization belongs. If you have no measurement yet, create the smallest representative benchmark/profile first; ripwire cannot infer runtime cost from source shape.

`<dir>` = repo root.

1. **Pin the measured evidence** — record the workload, baseline, profiler/trace result, and the symbol or subsystem it implicates. Keep the same workload for the after measurement.

2. **Navigate the measured surface** — `ripwire <dir> --for="measured operation or symbol" --detail=3`, then `--callers=SYM`, `--callees=SYM`, or `--around=SYM` as needed. This turns runtime evidence into a bounded source-reading set without pretending the graph measured execution.

3. **Maintenance/change-risk context** — `ripwire <dir> --hotspots --legend=compact` Output: `<hotspots>` ranked by `score = churn × ccx` (churn = git commit frequency over 12mo; ccx = cognitive complexity). The `top=` attribute names the highest-complexity function in each file. High-score files are frequently changed and structurally complex: useful evidence about optimization risk and validation scope, but structural evidence, not runtime heat. **A slowdown/regression traced to a specific change, not an all-time read** — use the recent-churn lens: `ripwire <dir> --hotspots --legend=compact --since="2 weeks ago"` (or `--since=HEAD~20` for a deterministic rev) ranks by commits after that point instead of all-history, which is the right lens for "this got slower after X" rather than a static hot-function scan.

4. **Static dependency + shape hypotheses** — `ripwire <dir> --metrics --legend=compact --top-k=50` Output: the ranked map with `in=` (fan-in), `cx=`/`ccx=` (complexity), `cbo=` (coupling between objects — how many other types this symbol touches), `loc=` (body size), and `nest=` (max nesting depth) on each symbol. `in=` is static dependency fan-in, not execution frequency. Use `cbo`/`nest`/`loc` to form code-reading hypotheses inside the already-measured surface: coupling may constrain a rewrite, nesting may hide branchy or quadratic work, and large bodies may combine unrelated work. **Read `nest=` with its profile, never alone** — it is a max, so `humps=` (regions reaching the nesting bar) and `deep=` (lines inside them, a floor) on the same row are what separate a body that *sustains* depth from a long flat one whose max is a single inner loop; `deep/loc` is the discriminator (→ **ripwire-quality-bar**). Confirm every suspected bottleneck with the benchmark/profile. **On C-family/C# code, discount a `ppalt=`-carrying body:** `cx=`/`ccx=`/`nest=`/`loc=`/`locals=` sum ALL `#else`/`#ifdef` branches, not just the one your build compiles, so a hot function that also happens to be preprocessor-heavy can look structurally worse than the code path actually executing.

4a2. **Join the measured heat onto the static findings** — `ripwire <dir> --lint --legend=compact --with-profile=REPORT`

REPORT is a RIPWIRE_PROFILE build's own stderr report (its `#PROF_TSV` block, verbatim). Every `--lint` finding whose enclosing symbol contains a `PROFILE_SCOPE` site gains `heat_*` attributes — the scope's measured calls, total_ms, and whichever counter columns that run armed (`heat_l1d_mpki` etc.; an ABSENT column was not measured, never zero). This is the one-command answer to "which of these cache-* rows are actually HOT": static shape × PMU weight (SYZYGY's advice mode, Hundt CGO 2006). `heat_joined="0"` on the root is honest — no finding sits inside a profiled scope — never an error.

4b. **If the profile points at MEMORY, not compute** — cheapest first, `ripwire <dir> --lint --legend=compact` runs the built-in **cache-\* pack** (8 static data-layout checks, e.g. `cache-gather-subscript`, `cache-vector-of-indirect`, `cache-pointer-chase-loop`) as part of an ordinary lint pass — no profile required, so it is worth a look before reaching for the heavier lens below. When a specific struct is already implicated, `--field-affinity[=STRUCT]`

**When to reach for it.** The measurement already implicates a struct-heavy path and the *shape* of the evidence says data layout, not algorithm: cache-miss or memory-stall counters dominating the profile, a loop whose cost does not track its instruction count, a hot/cold field mix (a couple of fields read on every pass, a dozen touched only on cold paths), or a wide struct threaded through many callers. Bare = every aggregate in the repo ranked by separation cost; `=STRUCT` narrows to the one the profile named — prefer the narrow form, per this skill's stop rule.

Output: per struct, which fields the indexed C/C++/ObjC functions access TOGETHER, diffed against the declared field order and 64-byte cache-line geometry (Chilimbi's separation weight, PLDI 1999 — cited, not invented here). Exactly two findings fire, both with a direction defensible in one sentence: `split-line` (a co-accessed pair at `wt="0.00"`, i.e. ≥64 bytes apart — **no** field order can put them on one line) and `straddle` (one co-accessed field crossing a line boundary, so every access to that ONE field touches two lines).

**What it does N