@nklisch/pi-agile-workflow 0.15.3

package/skills/perf-scout/references/distributed-systems.md

@@ -0,0 +1,150 @@
+# Distributed Systems — Perf-Scout Strategy Lens
+
+> **When to load this lens**: multi-node/service code, queues, RPC, replication,
+> cross-region calls, coordination, fan-out/fan-in, shared databases under load.
+>
+> **Where these ideas come from**: large-scale distributed systems (search,
+> storage, streaming), CDNs, and the queueing-theory school of tail-latency
+> control. The wins here are about *moving work, spreading load, and cutting
+> coordination* — and they often trade consistency for speed, so each candidate
+> must name what consistency it gives up. Every entry is a *candidate* hypothesis,
+> not a proven win. Cite `file:line`, attribute the source, give a validation path.
+
+## Detection signals (where this lens might apply — not proof)
+- A single shared DB/service under load from many clients (hot partition risk).
+- Synchronous cross-service/cross-region calls on a user-facing path.
+- Fan-out to many backends where one slow node stalls the whole response (tail latency).
+- Strong-consistency coordination (locks, two-phase, leader round-trips) on a hot path.
+- Unbounded queues / no backpressure; load spikes cause collapse.
+- Read-heavy data served from a single primary.
+- Per-request work that could be precomputed/streamed/pushed.
+
+## Strategies
+
+### 1. Partition / shard by key
+- **Borrowed from**: distributed databases, search indexes.
+- **The idea**: split data and load across shards by a key so no single node is the bottleneck; route each request to its shard.
+- **Code signals**: one DB/instance serving all keys; a hot table/partition.
+- **Speculative win**: throughput could scale toward shard count if keys are well-distributed; smaller per-node working set.
+- **Cost / risk**: cross-shard queries and rebalancing; hot-key skew.
+- **Validate by**: per-shard load distribution; throughput under partitioned load.
+
+### 2. Read replicas / read-write split
+- **Borrowed from**: database replication, CQRS.
+- **The idea**: serve reads from replicas and reserve the primary for writes; scale reads horizontally.
+- **Code signals**: read-heavy workload all hitting the primary.
+- **Speculative win**: read throughput might scale toward replica count if reads dominate and lag is tolerable.
+- **Cost / risk**: replication lag → stale reads; routing logic.
+- **Validate by**: read QPS capacity; staleness tolerance check.
+
+### 3. Consistent hashing for placement
+- **Borrowed from**: Karger et al. 1997 (consistent hashing / random trees); adopted by Dynamo and distributed caches.
+- **The idea**: place keys on nodes via consistent hashing so adding/removing a node remaps only ~1/N of keys instead of reshuffling everything.
+- **Code signals**: modulo-based sharding that reshuffles everything on resize; cache cold-start after scaling.
+- **Speculative win**: minimal data movement on topology change; stable cache hit rates.
+- **Cost / risk**: plain consistent hashing balances no better than random, so hot keys still overload a node; needs virtual nodes, and the *consistent-hashing-with-bounded-loads* variant (Mirrokni & Thorup, Google 2016/2018) to cap per-node load.
+- **Validate by**: remap fraction on node change; per-node load balance under skewed keys.
+
+### 4. Tail-latency hedging / speculative retries
+- **Borrowed from**: Dean & Barroso, "The Tail at Scale" (2013) — hedged and tied requests; search backends.
+- **The idea**: when a fan-out request is slow past a percentile, send a duplicate to another replica and take the first to respond (hedged); or enqueue on two replicas that cancel each other once one starts (tied requests), cutting wasted work.
+- **Code signals**: p99 dominated by a few slow backends in a fan-out; one slow node stalling responses.
+- **Speculative win**: large p99/p999 reduction with small extra load (the paper reports a hedge after a 10ms delay cut p99.9 dramatically for ~2% more requests).
+- **Cost / risk**: extra request volume that can backpressure a loaded downstream; diminishing returns at the tail; safe only for idempotent reads.
+- **Validate by**: p99/p999 with hedging on/off; measure added load; tune the hedge-delay percentile.
+
+### 5. Backpressure & load shedding
+- **Borrowed from**: reactive streams, network flow control.
+- **The idea**: bound queues and propagate backpressure; shed or degrade low-priority load before the system collapses, instead of unbounded buffering.
+- **Code signals**: unbounded in-memory queues; latency climbing without limit under spikes.
+- **Speculative win**: graceful degradation; bounded latency; avoids cascading failure (a stability + latency win).
+- **Cost / risk**: dropping/deferring work; priority policy.
+- **Validate by**: latency and success rate under overload tests.
+
+### 6. Locality-aware routing / edge
+- **Borrowed from**: CDNs, geo-distributed systems.
+- **The idea**: serve from the node/region nearest the data or the user; cache/compute at the edge to cut round-trip distance.
+- **Code signals**: cross-region calls on a user path; static/derivable content fetched from a distant origin.
+- **Speculative win**: could lower network latency and origin load if requests are geographically dispersed.
+- **Cost / risk**: data placement and invalidation across regions.
+- **Validate by**: per-region latency; edge hit rate.
+
+### 7. Relax consistency where the domain allows (eventual / CRDT)
+- **Borrowed from**: Dynamo (eventual consistency); CRDTs (Shapiro, Preguiça, Baquero & Zawirski 2011 — strong eventual consistency).
+- **The idea**: replace strong coordination with eventual consistency or conflict-free replicated data types where the use case tolerates it, removing coordination from the hot path. CRDTs converge without consensus by construction.
+- **Code signals**: distributed locks/2PC/leader round-trips guarding data that could converge instead.
+- **Speculative win**: might remove coordination latency and raise availability/throughput if the domain tolerates the relaxed model.
+- **Cost / risk**: weaker guarantees; CRDT convergence/merge semantics (state- vs op-based) must fit the domain, and metadata can grow. High design cost.
+- **Validate by**: latency without coordination; correctness against the relaxed model.
+
+### 8. Asynchronous / queue-decoupled work
+- **Borrowed from**: message queues, event-driven architectures.
+- **The idea**: move non-critical work (emails, indexing, analytics, derived updates) off the request path onto a queue/worker; return to the user sooner.
+- **Code signals**: user request blocks on slow side effects not needed for the response.
+- **Speculative win**: request latency may drop toward the critical path if the deferred work is truly off the response; smooths spikes.
+- **Cost / risk**: eventual completion; failure/retry semantics; ordering.
+- **Validate by**: request latency before/after; queue lag monitoring.
+
+### 9. Batch / stream across the wire
+- **Borrowed from**: gRPC streaming, Kafka batching.
+- **The idea**: batch many small RPCs into one, or stream results, instead of one request-response per item; coalesce cross-service chatter.
+- **Code signals**: per-item RPC in a loop across a service boundary; chatty microservice calls.
+- **Speculative win**: could cut round-trips and per-call overhead if calls are batchable and not already pipelined.
+- **Cost / risk**: batch error handling; streaming backpressure.
+- **Validate by**: round-trip count; throughput.
+
+### 10. CQRS / precomputed read models
+- **Borrowed from**: event sourcing, CQRS.
+- **The idea**: maintain denormalized read models updated from a write/event log so reads are simple lookups instead of expensive cross-aggregate queries.
+- **Code signals**: complex multi-join/aggregate queries rebuilt per read; read and write shapes fighting each other.
+- **Speculative win**: reads could become cheap lookups if the read model fits the query shape; read and write paths may scale independently.
+- **Cost / risk**: eventual consistency of the read model; projection maintenance.
+- **Validate by**: read latency; projection lag.
+
+### 11. Colocate compute with data
+- **Borrowed from**: map-reduce data locality, stored procedures, pushdown.
+- **The idea**: move the computation to where the data lives (push filters/aggregations into the store, run logic in the DB or near the dataset) instead of shipping large data to the compute.
+- **Code signals**: pulling large result sets to the app to filter/aggregate; ship-data-to-code patterns.
+- **Speculative win**: could cut data movement, network, and serialization if the filter/aggregation is highly reductive.
+- **Cost / risk**: logic in the data tier is harder to test/version; portability.
+- **Validate by**: bytes moved; end-to-end latency.
+
+### 12. Adaptive / least-loaded routing
+- **Borrowed from**: power-of-two-choices (Mitzenmacher et al.), join-shortest-queue load balancing.
+- **The idea**: instead of round-robin or random, sample two backends and route to the less-loaded one (fewest in-flight requests). Cheap partial state buys exponentially better balance than blind routing.
+- **Code signals**: round-robin/random LB while one slow or warm node piles up a queue; latency variance traced to uneven backend load.
+- **Speculative win**: might flatten queueing latency and the tail under load with O(1) per-request cost; no global coordination.
+- **Cost / risk**: needs a load/inflight signal per backend; stale load info can herd traffic; ties with hedging budget.
+- **Validate by**: per-backend queue depth and p99 under load test, round-robin vs power-of-two.
+
+### 13. Request coalescing / single-flight dedup
+- **Borrowed from**: single-flight, cache-stampede prevention, request collapsing at gateways.
+- **The idea**: when many concurrent callers ask for the same key, run one backend call and fan the single result out to all waiters, instead of N identical queries. Opposite of hedging — collapses duplicates rather than spawning them.
+- **Code signals**: hot key hit by many clients at once; thundering herd on cache miss/expiry; identical queries firing in parallel.
+- **Speculative win**: could collapse duplicate backend work to ~1 per key, cutting DB/upstream load and tail latency on cache misses.
+- **Cost / risk**: a stalled or failing leader call blocks/fails all waiters; only safe for read-shareable results; per-process unless backed by a distributed lock.
+- **Validate by**: duplicate-query count and DB load under a concurrent same-key burst; latency on cache-miss storms.
+
+### 14. Cell-based architecture (bulkhead isolation)
+- **Borrowed from**: AWS cell-based architecture, the bulkhead pattern.
+- **The idea**: partition the whole stack into independent, fixed-size cells (each a full replica) and route a tenant/key to one cell. Capacity scales by adding cells, and a hot or failing cell can't drag the rest down.
+- **Code signals**: one shared pool where a single noisy tenant or partition degrades everyone; no failure-isolation boundary.
+- **Speculative win**: might let throughput scale linearly with cell count while bounding the blast radius of overload to ~1/N of traffic (a scaling + stability candidate, not a per-request speedup).
+- **Cost / risk**: cross-cell operations and routing/placement complexity; per-cell overhead; rebalancing tenants between cells.
+- **Validate by**: per-cell load distribution; tail latency and error rate when one cell is saturated.
+
+### 15. Request deadlines + cancellation propagation
+- **Borrowed from**: gRPC deadlines (propagated across hops, unlike a per-hop timeout); Go `context` deadline/cancellation.
+- **The idea**: give each request a single time budget and propagate it (plus cancellation) down the call chain, so when the caller's deadline passes or it abandons the request, every downstream hop stops working on it instead of finishing doomed work.
+- **Code signals**: per-hop timeouts that don't compose into an end-to-end budget; downstream work that keeps running after the client gave up; no `context`/deadline threaded through calls.
+- **Speculative win**: could reclaim capacity spent on already-doomed requests and tighten the tail under load if much work is currently abandoned mid-flight.
+- **Cost / risk**: cancellation must be honored at each layer (and partial side effects undone); too-tight deadlines can amplify failures; clock-skew across services.
+- **Validate by**: fraction of work cancelled vs completed-after-deadline; tail latency and goodput under overload with deadlines on/off.
+
+### 16. Adaptive concurrency limits + retry budgets
+- **Borrowed from**: Netflix concurrency-limits (AIMD / gradient limiters, after TCP congestion control — gradient = RTT_noload / RTT_actual); retry budgets; Little's Law for queue sizing.
+- **The idea**: dynamically cap in-flight requests by watching latency (additively grow the limit while healthy, multiplicatively shrink when queueing appears) instead of a fixed pool, and cap retries as a small fraction of live traffic (a retry *budget*) so failures don't trigger a retry storm. Size any bounding queue with Little's Law (L = λ·W).
+- **Code signals**: hand-tuned fixed thread/connection pools; per-call retries with no global cap; latency collapsing under load while a static limit stays wide open; retry amplification during partial outages.
+- **Speculative win**: might hold throughput near the knee and prevent congestion collapse and retry storms if load is bursty and limits are currently static.
+- **Cost / risk**: limiter can misread noisy latency and over-throttle; needs a clean RTT/inflight signal; interacts with hedging and load-balancer choices.
+- **Validate by**: goodput and p99 under a load/overload test, static vs adaptive limit; retries as a percentage of requests during an injected downstream fault.

package/skills/perf-scout/references/game-engine-and-realtime.md

@@ -0,0 +1,136 @@
+# Game-Engine & Realtime — Perf-Scout Strategy Lens
+
+> **When to load this lens**: per-frame/per-tick loops, simulations, spatial
+> queries, large entity/object collections, rendering, soft real-time budgets,
+> allocation churn inside a loop.
+>
+> **Where these ideas come from**: AAA game engines, physics/simulation, and
+> real-time graphics — domains that must do enormous work inside a fixed
+> ~16ms/frame budget, which forces the most disciplined performance engineering in
+> software. Many of these ideas transfer surprisingly well to ordinary
+> batch/server code. Every entry is a *candidate* hypothesis, not a proven win.
+> Cite `file:line`, attribute the source, give a validation path.
+
+## Detection signals (where this lens might apply — not proof)
+- A main loop / tick / frame / step that runs over a collection every cycle.
+- Collections of "entities"/"objects" with heterogeneous behavior iterated per cycle.
+- Spatial queries: nearest-neighbor, range, collision, "what's near X" done by scanning all.
+- Allocations or temporary objects created inside the per-cycle loop.
+- Recomputing the same derived state every frame even when inputs didn't change.
+- Processing far-away / off-screen / low-impact items at full fidelity.
+- Variable timestep tied to frame rate; simulation jitter.
+- Hot loop touches one field of a wide struct across a large array (cache waste).
+
+## Strategies
+
+### 1. Entity-Component-System (ECS) / data-oriented layout
+- **Borrowed from**: modern game engines (Unity DOTS, Bevy, EnTT, flecs).
+- **The idea**: store entities' components in contiguous per-component arrays and process them in tight systems, instead of arrays of polymorphic objects with virtual `update()` calls.
+- **Code signals**: `for obj in objects: obj.update()` over heterogeneous objects; OOP entity hierarchies on a hot loop.
+- **Speculative win**: cache-friendly streaming, vectorizable systems, no virtual-dispatch per entity.
+- **Cost / risk**: a big architectural shift; overkill for small collections.
+- **Validate by**: per-system benchmark; cache-miss counters — profile via perf-design.
+
+### 2. ECS storage choice: archetype vs sparse-set
+- **Borrowed from**: ECS internals — archetype/table storage (Unity DOTS, flecs, Bevy default) vs sparse-set storage (EnTT, Bevy's opt-in `SparseSet`).
+- **The idea**: archetype storage packs entities sharing a component set into dense tables — fast multi-component iteration, but adding/removing a component moves the entity to another table. Sparse-set storage keeps each component in its own set — cheap add/remove, slower multi-component iteration. Pick per access pattern; some engines let you choose per component.
+- **Code signals**: ECS already in use but components churn (added/removed) every frame on a query-heavy path, or vice-versa.
+- **Speculative win**: matching storage to the dominant operation (iterate vs mutate) could cut the cost of whichever dominates.
+- **Cost / risk**: wrong choice penalizes the hot operation; mixed workloads may want a hybrid (flecs 4.1 / AoSoA).
+- **Validate by**: benchmark iteration vs structural-change rates on the real workload; compare storage modes.
+
+### 3. Spatial partitioning for proximity queries
+- **Borrowed from**: collision detection, rendering (grids, quadtree/octree, BVH, k-d tree, spatial hash).
+- **The idea**: index objects by position so "what's near X" / collision / range queries examine only nearby cells instead of all N objects.
+- **Code signals**: nested loop over all pairs for collision/distance; `for a: for b: if near(a,b)`.
+- **Speculative win**: O(n²) all-pairs → ~O(n) or O(n log n) neighbor queries.
+- **Cost / risk**: structure maintenance as objects move; cell-size tuning.
+- **Validate by**: query count and timing vs. object count — profile via perf-design.
+
+### 4. Object pooling (no allocation in the loop)
+- **Borrowed from**: game engines (bullets, particles, enemies).
+- **The idea**: pre-allocate and recycle objects from a pool so the per-frame loop never allocates or triggers GC.
+- **Code signals**: `new`/allocation inside the tick loop; GC pauses correlated with the loop; particle/event spawn churn.
+- **Speculative win**: removes allocation and GC pauses from the hot loop — candidate for steadier frame time.
+- **Cost / risk**: must fully reset reused objects; pool sizing.
+- **Validate by**: allocations/frame; frame-time variance.
+
+### 5. Frame / linear (arena) allocator for transient data
+- **Borrowed from**: frame-centric engine memory (Naughty Dog frame allocators; arena/bump allocators).
+- **The idea**: serve all per-frame scratch (temp buffers, command lists, intermediate results) from a linear allocator that bumps a pointer, then reset the whole arena to zero at end of frame — no per-object free.
+- **Code signals**: many short-lived heap allocations whose lifetime is exactly one frame/request; `malloc`/`new` + matching frees clustered inside one cycle.
+- **Speculative win**: allocation reduces to a pointer bump and free to one integer reset; could remove allocator contention and fragmentation from the loop.
+- **Cost / risk**: dangling references if data outlives the frame; arena must be sized for the worst frame.
+- **Validate by**: allocation-time and frame-time variance with arena vs general allocator; verify no escapes.
+
+### 6. Structure-of-Arrays hot loops
+- **Borrowed from**: data-oriented design (SoA vs AoS); SIMD-friendly layouts.
+- **The idea**: when a hot loop reads only one or two fields of a wide record across a large array, store each field in its own array (SoA) so the loop streams only the bytes it touches and can autovectorize, instead of pulling whole structs through cache.
+- **Code signals**: tight loop over `items[i].oneField` on a struct with many other fields; low arithmetic intensity but high memory traffic; failed autovectorization.
+- **Speculative win**: fewer cache-line loads and unit-stride access could speed memory-bound loops and unlock SIMD.
+- **Cost / risk**: scattered random per-record access gets worse; splitting hurts code clarity; AoSoA is a middle ground.
+- **Validate by**: cache-miss / bandwidth counters and loop benchmark; confirm vectorization — profile via perf-design.
+
+### 7. Dirty-flagging / change-driven recompute
+- **Borrowed from**: scene graphs, UI layout engines, retained-mode rendering.
+- **The idea**: recompute derived state only when its inputs change (mark dirty on mutation, recompute lazily) instead of every frame.
+- **Code signals**: full transform/layout/derived recompute each frame regardless of change.
+- **Speculative win**: per-cycle work drops to only what changed.
+- **Cost / risk**: dirty-tracking correctness; missed invalidations cause stale state.
+- **Validate by**: count recomputes/frame; benchmark with realistic change rates.
+
+### 8. Level of Detail (LOD) / fidelity by impact
+- **Borrowed from**: rendering, physics LOD, simulation.
+- **The idea**: process distant/low-impact/off-screen items at reduced fidelity or lower frequency; full detail only where it matters.
+- **Code signals**: every item processed identically regardless of relevance; far/off-screen items at full cost.
+- **Speculative win**: large savings by spending compute where it's perceptible/important.
+- **Cost / risk**: fidelity transitions; correctness of the impact heuristic.
+- **Validate by**: cost per fidelity tier; quality check.
+
+### 9. Culling (skip invisible/irrelevant work)
+- **Borrowed from**: frustum/occlusion culling in renderers.
+- **The idea**: cheaply reject items that can't affect the result before doing expensive work on them (bounding-box test, visibility test, relevance filter).
+- **Code signals**: expensive per-item processing with no early reject; computing results that are then discarded/clipped.
+- **Speculative win**: skips the majority of items when most are irrelevant.
+- **Cost / risk**: cull test must be cheaper than the work saved; correctness of rejection.
+- **Validate by**: cull rate; benchmark with/without.
+
+### 10. Fixed timestep / decoupled update rate
+- **Borrowed from**: game loops, physics integration (Gaffer on Games, "Fix Your Timestep!", Glenn Fiedler).
+- **The idea**: run simulation at a fixed timestep accumulated independently of render/output rate for stable, cheaper, deterministic updates; interpolate between the last two states for display.
+- **Code signals**: per-frame work scaling with frame rate; jittery or rate-dependent simulation.
+- **Speculative win**: bounded, predictable per-cycle cost; determinism.
+- **Cost / risk**: interpolation for display; accumulator logic; spiral-of-death if a step exceeds budget.
+- **Validate by**: per-tick cost stability; determinism check.
+
+### 11. Double buffering / read-write separation
+- **Borrowed from**: rendering (front/back buffer), simulation state.
+- **The idea**: compute next state into a separate buffer while readers use the current one, then swap — avoids locking and read-during-write hazards, enables parallel update.
+- **Code signals**: readers and a writer contending on shared state per cycle; locks around per-frame state.
+- **Speculative win**: lock-free reads during update; parallel-friendly.
+- **Cost / risk**: double the memory; swap synchronization.
+- **Validate by**: contention metrics; frame-time benchmark.
+
+### 12. Job system / frame-budgeted parallelism
+- **Borrowed from**: engine job systems (fork-join over a frame; Naughty Dog fiber-based job system, Gyrling, GDC 2015).
+- **The idea**: break the frame's work into jobs scheduled across cores within the frame budget; spread the per-cycle workload over all cores.
+- **Code signals**: single-threaded per-frame work; idle cores; a frame budget being missed.
+- **Speculative win**: more work per frame within budget; better core use.
+- **Cost / risk**: job dependencies; scheduler overhead for tiny jobs.
+- **Validate by**: frame-time and core-utilization benchmark.
+
+### 13. Batch by type / sort to reduce state changes
+- **Borrowed from**: render-state batching, draw-call sorting.
+- **The idea**: group like work together (same type/shader/resource) and sort to minimize expensive state switches between items.
+- **Code signals**: interleaved heterogeneous operations each paying setup/teardown; frequent context switches per item.
+- **Speculative win**: amortizes setup across a batch; fewer expensive transitions.
+- **Cost / risk**: a sort/group pass; reordering must be valid.
+- **Validate by**: state-change count; throughput.
+
+### 14. Precompute / bake static work
+- **Borrowed from**: lightmap baking, navmesh precomputation.
+- **The idea**: move work that doesn't change at runtime into an offline/startup bake (precomputed tables, baked paths/visibility) so the hot loop just reads it.
+- **Code signals**: recomputing static-input results every cycle; expensive setup repeated at runtime.
+- **Speculative win**: removes invariant work from the runtime loop entirely.
+- **Cost / risk**: bake step and storage; rebake on input change.
+- **Validate by**: runtime cost with baked vs. computed data.

package/skills/perf-scout/references/gpu-and-accelerators.md

@@ -0,0 +1,130 @@
+# GPU & Accelerators — Perf-Scout Strategy Lens
+
+> **When to load this lens**: massively-parallel regular numeric work, large
+> array/matrix/tensor math, image/signal processing, convolutions, existing
+> GPU/CUDA/Metal/ROCm code, or compute-bound kernels that could move off the CPU.
+>
+> **Where these ideas come from**: GPU programming (CUDA, Metal, ROCm/HIP),
+> ML kernels (cuDNN, CUTLASS), HPC, and graphics. A GPU only wins when the work
+> has enough *arithmetic intensity* (FLOPs per byte moved) to feed thousands of
+> threads, and host↔device transfer often dominates a naive port — so these
+> ideas only matter once the work is regular, data-parallel, and big enough.
+> **Pair this lens with a roofline check first** (entry 1): decide memory-bound
+> vs compute-bound before optimizing, because the two need opposite fixes. Every
+> entry is a *candidate* hypothesis, not a proven win. Cite `file:line`,
+> attribute the source, give a validation path.
+
+## Detection signals (where this lens might apply — not proof)
+- Large element-wise / map operations over arrays (millions of elements).
+- Dense linear algebra: matrix multiply, convolution, FFT, tensor contractions.
+- Image, video, or signal processing done element-by-element on the CPU.
+- Existing GPU code (`.cu`/`.metal`/HIP kernels) with hand-rolled loops.
+- A hot numeric kernel that is regular (no data-dependent control flow) and huge.
+- ML inference/training math, embeddings, similarity at scale.
+- A CPU SIMD kernel already maxed out but still the bottleneck.
+
+## Strategies
+
+### 1. Roofline / arithmetic-intensity check (do this FIRST)
+- **Borrowed from**: the Roofline model (Williams, Waterman & Patterson, 2008).
+- **The idea**: before optimizing, plot the kernel's arithmetic intensity (FLOPs per byte moved) against peak compute and peak bandwidth. If it lands on the slanted bandwidth roof it is *memory-bound* (fix data movement); if on the flat roof it is *compute-bound* (fix the math/instruction mix). This decides which of the entries below even apply.
+- **Code signals**: a kernel being tuned blind; "make it faster" with no idea whether bytes or FLOPs are the wall; a low-intensity op (axpy, copy, reduction) expected to be compute-bound.
+- **Speculative win**: stops wasted effort — points at the *actual* ceiling so the right strategy is chosen.
+- **Cost / risk**: requires measuring/estimating bytes and FLOPs; the model is a guide, not exact.
+- **Validate by**: Nsight Compute roofline report (or compute the intensity by hand) to locate the kernel under the roof.
+
+### 2. Memory coalescing
+- **Borrowed from**: CUDA/GPU global-memory access model.
+- **The idea**: arrange access so the 32 threads of a warp touch contiguous, aligned global-memory addresses, letting the hardware merge them into as few transactions as possible (ideally 128-byte aligned).
+- **Code signals**: strided/scattered/transposed indexing in a kernel; each thread walking a row with a large stride; AoS layouts in device buffers.
+- **Speculative win**: fewer DRAM transactions per warp — a candidate large jump for memory-bound kernels (uncoalesced access can split one transaction into many).
+- **Cost / risk**: may force a layout change (SoA, transpose) elsewhere; only matters when memory-bound.
+- **Validate by**: Nsight Compute memory-throughput / global-load-efficiency report; before/after kernel timing.
+
+### 3. Shared-memory / on-chip tiling
+- **Borrowed from**: tiled matmul; blocked GEMM in cuBLAS/CUTLASS.
+- **The idea**: stage a block of data into on-chip shared memory once, then have the threads of the block reuse it many times, cutting redundant global-memory loads (classic blocked matrix multiply).
+- **Code signals**: a kernel re-reading the same global data across threads/iterations; stencils, GEMM, convolution loading neighbors repeatedly.
+- **Speculative win**: raises arithmetic intensity by reusing on-chip data — candidate for moving a memory-bound kernel toward compute-bound.
+- **Cost / risk**: shared memory is scarce and caps occupancy; bank conflicts; correct tiling/sync is fiddly.
+- **Validate by**: Nsight Compute (global traffic drop, shared-memory bank-conflict counters); compare against a library GEMM.
+
+### 4. Occupancy vs register/shared-memory pressure
+- **Borrowed from**: CUDA occupancy tuning.
+- **The idea**: enough resident warps per SM are needed to hide memory latency, but each thread's registers and each block's shared memory cap how many warps fit. Trading some per-thread register use (or shared memory) for more concurrent warps — or vice versa — can be the win.
+- **Code signals**: a kernel launching far fewer blocks than SMs; high register usage; low achieved occupancy; latency-bound kernel with idle SMs.
+- **Speculative win**: better latency hiding and SM utilization once occupancy is the limiter.
+- **Cost / risk**: more occupancy is not always better (register spilling hurts); needs measurement, not assumption.
+- **Validate by**: `nvcc --ptxas-options=-v` for register/shared usage; Nsight Compute achieved-occupancy and the occupancy calculator.
+
+### 5. Warp / wavefront divergence
+- **Borrowed from**: SIMT execution model (CUDA warps, AMD wavefronts).
+- **The idea**: when threads in a warp take different sides of a data-dependent branch, the warp serializes each path with the off-path threads masked. Restructure so a branch resolves uniformly across the warp (sort/partition by branch outcome, branchless predication, data reorganization).
+- **Code signals**: `if (data[tid] > x)` style data-dependent branches inside a kernel; per-thread early-exit; ragged loop bounds across threads.
+- **Speculative win**: removes serialized branch paths within a warp — candidate when divergence is high.
+- **Cost / risk**: reorganizing data to align branches has its own cost; only helps if divergence is actually significant.
+- **Validate by**: Nsight Compute branch-efficiency / warp-execution-efficiency counters; before/after timing.
+
+### 6. Kernel fusion
+- **Borrowed from**: ML compilers / elementwise fusion (cuDNN, XLA, Triton).
+- **The idea**: fuse a chain of elementwise or producer→consumer kernels into one, so intermediates stay in registers/shared memory instead of round-tripping through global memory, and you pay one launch instead of many.
+- **Code signals**: several small kernels run back-to-back over the same arrays; `a = f(x); b = g(a); c = h(b)` each as its own launch; a temp buffer written then immediately re-read.
+- **Speculative win**: fewer launches and global-memory round-trips — candidate for memory-bound elementwise chains.
+- **Cost / risk**: a fused kernel uses more registers/shared memory (can cut occupancy); harder to read; less reuse across call sites.
+- **Validate by**: count launches + global traffic in Nsight Systems/Compute; before/after end-to-end timing.
+
+### 7. Host↔device transfer amortization
+- **Borrowed from**: CUDA streams / async copy; pinned-memory DMA.
+- **The idea**: stop paying PCIe round-trips per call — keep data resident on the device across operations, batch transfers, use pinned (page-locked) host memory for faster DMA, and overlap copy with compute using non-default streams (copy chunk i+1 while computing chunk i).
+- **Code signals**: copy-up → one kernel → copy-down repeated in a loop; pageable host buffers; default-stream-only code; transfer time rivaling kernel time.
+- **Speculative win**: hides or removes transfer cost — often the single biggest factor in whether a GPU port wins at all.
+- **Cost / risk**: pinned memory is a limited resource; stream/overlap logic adds complexity; overlap needs separate non-default streams + pinned host memory.
+- **Validate by**: Nsight Systems timeline (copy vs compute overlap); measure host-device transfer time vs kernel time explicitly.
+
+### 8. Mixed precision (fp16 / bf16 / tf32)
+- **Borrowed from**: mixed-precision ML training/inference (NVIDIA AMP).
+- **The idea**: where accuracy tolerates it, run in fp16/bf16/tf32 instead of fp32 — roughly halving bytes moved and unlocking higher math throughput, optionally keeping a higher-precision accumulator.
+- **Code signals**: fp32-everywhere numeric kernels; ML inference; large arrays where a few bits of mantissa do not change the result materially.
+- **Speculative win**: less memory traffic and higher throughput — candidate when the workload is tolerant.
+- **Cost / risk**: accuracy loss, overflow/underflow (bf16 range vs fp16 precision); needs numerical validation; not safe everywhere.
+- **Validate by**: accuracy/error check against the fp32 baseline; bandwidth + timing on the reduced-precision kernel.
+
+### 9. Tensor-core / MMA fit
+- **Borrowed from**: NVIDIA Tensor Cores / matrix engines; CUTLASS MMA tiling.
+- **The idea**: matrix-multiply-accumulate hardware only fires when data type, layout, and tile shape match what the matrix engine wants (e.g. CUTLASS warp-level MMA tiles like 16×8×8). Shaping the problem as tiled GEMM in a supported precision lets the matrix units do the work.
+- **Code signals**: matmul/conv/attention implemented as plain fp32 loops; GEMM-shaped math not hitting tensor cores; awkward tile dimensions.
+- **Speculative win**: routes the math onto dedicated matrix units — a candidate large jump for GEMM-shaped, precision-tolerant work.
+- **Cost / risk**: strict shape/alignment/precision constraints; hardware-specific; easy to *think* you are using tensor cores when you are not.
+- **Validate by**: Nsight Compute tensor-core-utilization (pipe-active) counters; compare against cuBLAS/CUTLASS for the same op.
+
+### 10. Read-only / constant / texture memory paths
+- **Borrowed from**: CUDA memory hierarchy (constant cache, read-only `__ldg`/texture path).
+- **The idea**: route data that is constant for the kernel's lifetime through specialized cached paths — constant memory for warp-uniform broadcasts, the read-only data cache (`const __restrict__` / `__ldg`) for reused read-only inputs — to relieve the general L1/global path.
+- **Code signals**: lookup tables, filter weights, or coefficients read by every thread; read-only inputs not marked `const __restrict__`; broadcast-style same-address reads.
+- **Speculative win**: extra effective cache and broadcast for read-only data — candidate when reuse is high.
+- **Cost / risk**: constant memory is tiny; only helps specific access patterns (uniform broadcast / heavily reused read-only); easy to misapply.
+- **Validate by**: Nsight Compute cache hit-rate counters on the relevant path; before/after timing.
+
+### 11. Batch small kernels / more work per launch
+- **Borrowed from**: batched BLAS; CUDA Graphs; launch-latency amortization.
+- **The idea**: many tiny launches are dominated by per-launch overhead — batch them (batched GEMM, a grid covering all items, or a CUDA Graph capturing the sequence) so each launch does enough work to amortize the cost.
+- **Code signals**: a host loop launching one small kernel per item; thousands of micro-launches; grids far smaller than the device.
+- **Speculative win**: launch overhead amortized across more work — candidate when launches dominate over compute.
+- **Cost / risk**: batching needs uniform-ish work; CUDA Graphs add capture/update complexity; oversized grids can hurt locality.
+- **Validate by**: Nsight Systems launch density / gaps on the timeline; before/after throughput.
+
+### 12. Use a tuned library/primitive over a hand-rolled kernel
+- **Borrowed from**: cuBLAS, cuDNN, CUTLASS, Thrust; Metal Performance Shaders.
+- **The idea**: for standard operations (GEMM, conv, FFT, sort, scan, reduce), a vendor-tuned primitive is usually far faster than a hand-written kernel and already applies coalescing/tiling/tensor-core tricks — call it instead of reinventing it.
+- **Code signals**: a hand-written matmul/conv/sort/scan/reduce kernel; "I wrote my own GEMM"; standard ops reimplemented from scratch.
+- **Speculative win**: large headroom — hand kernels for standard ops often reach only a fraction of the tuned library's throughput.
+- **Cost / risk**: a dependency and an API to adopt; custom kernels can still win when fused with surrounding app-specific work; library shapes may not fit exactly.
+- **Validate by**: benchmark the kernel against the library primitive (e.g. compare against cuBLAS / MPSMatrixMultiplication) for the same problem size.
+
+### 13. Reconsider whether the GPU is the right tool at all
+- **Borrowed from**: roofline + Amdahl reasoning; HPC offload practice.
+- **The idea**: a GPU only wins when there is enough parallel, regular, arithmetic-heavy work to overcome transfer + launch overhead. Small, branchy, or transfer-bound work may be faster left on a well-vectorized CPU. Treat "offload to GPU" itself as a candidate to validate, not a default.
+- **Code signals**: small inputs; irregular/pointer-chasing work; a port that copies more than it computes; low arithmetic intensity with frequent host sync.
+- **Speculative win**: avoids a slower-than-CPU port; redirects effort to a lens that actually pays (CPU SIMD, locality, algorithmic).
+- **Cost / risk**: needs an honest CPU baseline; the answer is workload-specific.
+- **Validate by**: end-to-end GPU benchmark *including* transfer vs a tuned CPU baseline — profile via perf-design.

package/skills/perf-scout/references/idea-ranking.md

@@ -0,0 +1,75 @@
+# Idea Ranking — Perf-Scout
+
+> How the orchestrator ranks candidate ideas in Phase 4 and scores each lens.
+> This is a triage tool for **what to investigate first**, not a claim about
+> realized gains. Nothing here asserts a speedup is real — the ranking sorts
+> *hypotheses* by how worth-chasing they look.
+
+## The three per-idea axes
+
+Each scout already tags every idea on three axes. Use them as the inputs to the
+priority tier.
+
+| Axis | Question | Values |
+|---|---|---|
+| **Leverage** | If this idea pans out, how big is the plausible upside? | High / Medium / Low |
+| **Applicability** | How likely is it that this code actually fits the pattern? | Likely / Plausible / Speculative |
+| **Cost** | How much work + risk to try it (implementation effort, correctness/behavior risk, memory tradeoff)? | Low / Medium / High |
+
+Note the asymmetry: **Leverage** and **Applicability** are about *upside and fit*;
+**Cost** is the *price of finding out*. A cheap experiment with uncertain payoff
+can still rank high — the point is to surface what's worth a measurement.
+
+## Priority tiers
+
+Combine the axes into one of three tiers. The spirit: reward high plausible
+upside and high fit, discount by cost/risk.
+
+| Tier | Rough rule | Meaning |
+|---|---|---|
+| **Investigate-first** | High Leverage AND Applicability ≥ Plausible AND Cost ≤ Medium | Strong, well-located bet. Hand to perf-design to measure now. |
+| **Worth-a-look** | (High Leverage with High Cost) OR (Medium Leverage with Applicability ≥ Plausible) | Real candidate; needs a closer look or a cheap experiment before committing. |
+| **Long-shot** | Everything else — Low Leverage, or Speculative applicability, or High cost with modest upside | Keep on the deck for completeness; chase only if the obvious wins are exhausted. |
+
+Two tie-breakers, in order:
+1. **Cheaper-to-validate wins.** Between two same-tier ideas, rank the one that's
+   easier to confirm (a quick benchmark) above the one needing a big rewrite to
+   even test.
+2. **Borrowed-from novelty.** A non-obvious idea from a different domain (a game
+   engine layout trick on a web service) ranks above a generic one of equal
+   tier — surfacing the unexpected is this skill's reason to exist.
+
+## "Top 5 to investigate first"
+
+After tiering, pick the five strongest Investigate-first ideas (fall through to
+Worth-a-look if fewer than five qualify) for the report's headline callout and
+the user summary. Spread them across lenses where possible — five ideas from one
+lens is less useful than five angles from five domains.
+
+## Lens opportunity-density score (0-10)
+
+Score each lens for how much *plausible headroom* it surfaced. This is an
+**opportunity** signal — high means "lots to chase here," NOT "the code is bad."
+A low score is good news (little obvious headroom in that dimension).
+
+| Score | Meaning |
+|---|---|
+| 0-2 | Lens barely applies, or only Long-shot ideas. Little headroom in this dimension. |
+| 3-4 | A few Worth-a-look ideas; no strong bets. Modest headroom. |
+| 5-6 | Several Worth-a-look or one Investigate-first. Real headroom worth a pass. |
+| 7-8 | Multiple Investigate-first ideas, well-located. Rich headroom — prioritize this lens. |
+| 9-10 | Many high-leverage, well-located, cheap-to-validate ideas. Exceptional headroom; likely the highest-value place to dig. |
+
+There is **no overall code score** — unlike bug-scan, a high number here is an
+invitation to investigate, not a verdict on quality. Report per-lens densities
+and let the Top-5 callout carry the headline.
+
+## Honesty guardrails
+
+- Tiers rank *hypotheses*, not measured wins. The report and summary must keep
+  that framing: "ranked candidates to investigate," never "ranked improvements."
+- An idea's tier can be high while its Applicability is Speculative — that's fine,
+  it just means "high upside if it fits, worth a quick check." Don't launder
+  Speculative into Likely to inflate the tier.
+- If you can't articulate a validation path for an idea, it doesn't belong on the
+  deck at any tier — drop it.