@nklisch/pi-agile-workflow 0.15.3

package/skills/perf-scout/references/io-and-batching.md

@@ -0,0 +1,135 @@
+# I/O & Batching — Perf-Scout Strategy Lens
+
+> **When to load this lens**: DB/network/disk calls, per-item I/O inside loops,
+> serialization, syscalls, N+1 patterns, chatty service boundaries.
+>
+> **Where these ideas come from**: database engines, high-throughput servers, OS
+> kernels (io_uring, zero-copy), and storage systems. I/O is usually thousands of
+> times slower than CPU, so *the number and shape of I/O operations dominates wall
+> time* on most services. 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 query/request/read inside a loop (`for row: db.get(row.id)`) — the N+1 shape.
+- Sequential awaits of independent I/O (covered also by the parallelism lens).
+- Row-at-a-time reads/writes against a DB or file.
+- Small frequent syscalls (per-byte/per-line read/write, unbuffered I/O).
+- Large objects serialized to JSON/text on a hot path.
+- Repeated connection setup/teardown; no pooling.
+- Full-payload transfers where a subset of fields is used.
+- Small synchronous request/response round-trips on default sockets (possible Nagle/delayed-ACK stalls).
+- Large file→socket transfers the app never inspects; bulk streaming that pollutes the cache.
+
+## Strategies
+
+### 1. Eliminate N+1 with batch/bulk queries
+- **Borrowed from**: ORM dataloaders, SQL `IN`/joins.
+- **The idea**: replace per-item queries with one bulk query (`WHERE id IN (...)`, a join, or a `dataloader` that coalesces a tick's keys).
+- **Code signals**: a DB/RPC call inside a loop keyed by the loop variable.
+- **Speculative win**: N round-trips collapse to 1; latency drops from N×rtt to 1×rtt.
+- **Cost / risk**: large `IN` lists; result reassembly; query plan changes.
+- **Validate by**: count round-trips; end-to-end latency — perf-design.
+
+### 2. Batch writes
+- **Borrowed from**: bulk inserts, LSM write batching, group commit.
+- **The idea**: accumulate writes and flush as one multi-row insert / pipelined batch / single transaction instead of one statement per item.
+- **Code signals**: `for item: insert(item)` — per-row inserts/updates.
+- **Speculative win**: amortizes round-trip and commit overhead across the batch.
+- **Cost / risk**: partial-failure handling; batch sizing; latency to durability.
+- **Validate by**: write throughput across batch sizes.
+
+### 3. Buffer small I/O
+- **Borrowed from**: stdio buffering, log writers.
+- **The idea**: wrap raw streams in a buffer so many small reads/writes become few large syscalls.
+- **Code signals**: per-line/per-byte read/write; unbuffered file or socket I/O in a loop.
+- **Speculative win**: orders-of-magnitude fewer syscalls; less kernel-crossing overhead.
+- **Cost / risk**: flush discipline; buffered data lost on crash without flush.
+- **Validate by**: syscall count (strace/dtrace); throughput.
+
+### 4. Connection / resource pooling
+- **Borrowed from**: DB connection pools, HTTP keep-alive.
+- **The idea**: reuse connections/clients from a pool instead of establishing a new one per call.
+- **Code signals**: new client/connection created per request; TLS/handshake cost per call.
+- **Speculative win**: removes setup/teardown latency from every call.
+- **Cost / risk**: pool sizing; stale-connection handling.
+- **Validate by**: per-call latency breakdown; handshake counts.
+
+### 5. Zero-copy transfer (`sendfile` / `splice` / `mmap`)
+- **Borrowed from**: kernel I/O, high-throughput servers, databases.
+- **The idea**: avoid copying bytes through user space — `sendfile`/`splice` send file→socket straight from the page cache (DMA to the NIC, no user-space round-trip), `mmap` for large reads, slice-not-copy buffer handling.
+- **Code signals**: `read()`-into-buffer-then-`write()` loops for large payloads the app never inspects; many intermediate buffer copies.
+- **Speculative win**: a static-file send path *might* drop from ~4 copies to ~2 (or near-0 with NIC scatter-gather), cutting CPU and memory bandwidth; reported CPU drops are large but workload-specific.
+- **Cost / risk**: only helps when the app doesn't need to touch the bytes; `mmap` page-fault and lifetime subtleties; platform-specific (`sendfile`/`splice` are Linux).
+- **Validate by**: CPU/bandwidth profiling on the transfer path; copy count via `perf`/`strace` — profile via perf-design.
+
+### 6. Async batched submission with io_uring
+- **Borrowed from**: Linux io_uring, AIO.
+- **The idea**: submit many I/O operations in one batch and reap completions asynchronously over a shared submission/completion ring. Registered (pre-pinned) buffers and registered file descriptors let the kernel skip per-op mapping/lookup; zero-copy send is supported, and zero-copy *receive* landed in Linux 6.15 (2025).
+- **Code signals**: many independent reads/writes issued one syscall at a time; epoll loops with high syscall overhead under high connection counts.
+- **Speculative win**: fewer syscalls and deeper queue depth *might* raise throughput; public io_uring numbers cite ~30-40% single-flow gains and 2-2.5× over epoll on some network workloads — treat as a ceiling, not a promise.
+- **Cost / risk**: significant complexity; Linux-only and kernel-version-sensitive (newest features need recent kernels); ordering/error handling; buffer lifetime under zero-copy. Zero-copy *receive* in particular is not generally available on any 6.15 host — it requires NIC support for header/data split, flow steering, and RSS, so treat it as conditional on the hardware, not a given.
+- **Validate by**: IOPS/throughput benchmark and syscall counts (`strace -c`) vs the current path — profile via perf-design.
+
+### 7. Vectored I/O (`readv`/`writev`)
+- **Borrowed from**: scatter/gather I/O, `readv`/`writev`/`preadv`/`pwritev`.
+- **The idea**: read or write several non-contiguous buffers in a single syscall instead of one syscall per buffer (e.g. write a header and body together without concatenating them first).
+- **Code signals**: multiple back-to-back `write()`s of related buffers; allocating a temp buffer just to concatenate fragments before one write.
+- **Speculative win**: one syscall replaces several, and avoids the concatenation copy/allocation.
+- **Cost / risk**: minor — iovec setup; per-syscall byte limits (`IOV_MAX`).
+- **Validate by**: syscall count (`strace -c`); throughput on the fragmented-write path.
+
+### 8. Project only what you need (column/field pushdown)
+- **Borrowed from**: columnar databases, GraphQL field selection.
+- **The idea**: fetch only required columns/fields rather than `SELECT *` or full objects; push filters/predicates down to the store.
+- **Code signals**: `SELECT *` then use two fields; fetch full document to read one field; filter in app after fetching everything.
+- **Speculative win**: less data transferred, deserialized, and held.
+- **Cost / risk**: more specific queries to maintain; index coverage.
+- **Validate by**: bytes transferred; query timing — profile via perf-design.
+
+### 9. Cheaper serialization format
+- **Borrowed from**: RPC systems (protobuf, FlatBuffers, Cap'n Proto), columnar formats.
+- **The idea**: replace verbose text serialization (JSON/XML) on hot paths with a compact binary format (protobuf), or a zero-parse format (FlatBuffers/Cap'n Proto) where fields are read directly out of the wire buffer with no unpacking step — good for read-mostly data.
+- **Code signals**: JSON encode/decode showing up on a hot path; large text payloads; decode-then-read-one-field access patterns.
+- **Speculative win**: less CPU for (de)serialization and smaller payloads; zero-parse formats *might* make field reads near-free by skipping the decode step entirely.
+- **Cost / risk**: schema management and interop cost; zero-parse formats trade serialize-side speed and in-place mutability (arena allocation) for read speed, so they fit read-mostly, not write-heavy, data.
+- **Validate by**: (de)serialization CPU and payload size benchmark vs the current format — profile via perf-design.
+
+### 10. Compression on the wire / at rest
+- **Borrowed from**: storage engines, CDNs (gzip/zstd/lz4).
+- **The idea**: compress large payloads to trade CPU for bandwidth where the link or disk is the bottleneck — lz4 for max speed at a modest ratio, zstd for a notably better ratio at higher (but still fast) CPU cost.
+- **Code signals**: large repetitive payloads over a network/disk boundary; bandwidth-bound transfers.
+- **Speculative win**: fewer bytes moved; *might* be faster when I/O-bound. On fast links lz4's lighter CPU often wins; on slow links zstd's better ratio often wins — the crossover is workload-specific.
+- **Cost / risk**: CPU cost; counterproductive when CPU-bound or data is incompressible.
+- **Validate by**: end-to-end time with compression on/off and across codecs/levels; compression ratio — profile via perf-design.
+
+### 11. Read-ahead / prefetch / pagination tuning
+- **Borrowed from**: OS readahead, DB prefetchers.
+- **The idea**: fetch the next chunk before it's needed (prefetch upcoming pages), or right-size page/fetch sizes so you neither over-fetch nor make too many round-trips.
+- **Code signals**: tiny page sizes causing many round-trips; strictly sequential consumption that could prefetch.
+- **Speculative win**: hides fetch latency; fewer round-trips.
+- **Cost / risk**: wasted prefetch if access turns random; memory for buffered pages.
+- **Validate by**: round-trip count and latency across page sizes — profile via perf-design.
+
+### 12. Coalesce / debounce chatty calls
+- **Borrowed from**: UI event debouncing, write coalescing.
+- **The idea**: merge bursts of small requests/writes to the same target within a window into one call.
+- **Code signals**: high-frequency small updates to the same resource; per-keystroke/per-event I/O.
+- **Speculative win**: fewer total operations; less load on the target.
+- **Cost / risk**: added latency to first effect; lost intermediate states.
+- **Validate by**: operation count; latency budget check — profile via perf-design.
+
+### 13. Disable Nagle on small-message latency paths (`TCP_NODELAY`)
+- **Borrowed from**: low-latency RPC/gRPC, trading systems, interactive protocols.
+- **The idea**: Nagle's algorithm holds small writes waiting for an ACK while the peer's delayed-ACK holds the ACK waiting for data — a feedback loop that *can* inject up to ~40 ms stalls per request-response. Setting `TCP_NODELAY` (and/or coalescing app-side into one write) breaks it.
+- **Code signals**: request/response protocol with small payloads; a write-then-immediately-read round-trip per call; sockets left at defaults; sporadic ~40 ms latency spikes.
+- **Speculative win**: tail latency on small synchronous round-trips *might* collapse by tens of milliseconds.
+- **Cost / risk**: more, smaller packets — keep Nagle on for bulk-transfer paths; only a win for latency-sensitive small messages, not throughput.
+- **Validate by**: per-request latency distribution (p99/tail) with `TCP_NODELAY` on/off; packet capture showing delayed-ACK stalls — profile via perf-design.
+
+### 14. Direct I/O for self-cached / streaming workloads (`O_DIRECT`)
+- **Borrowed from**: databases (WAL/data files), high-throughput storage engines.
+- **The idea**: bypass the kernel page cache so reads/writes go straight to disk, when the app maintains its own cache or streams data it won't re-read — avoiding double-buffering and cache pollution.
+- **Code signals**: large sequential reads/writes of write-once or app-cached data; an app-level buffer cache layered on top of the OS page cache; cache thrash from streaming bulk data.
+- **Speculative win**: less memory pressure and CPU copy overhead; more predictable latency for self-managing engines.
+- **Cost / risk**: strict sector-alignment requirements; loses kernel readahead/caching, so it *hurts* re-read-heavy or small-random workloads; mixing `O_DIRECT` and buffered access to the same file is unsafe.
+- **Validate by**: throughput and memory/page-cache pressure with direct vs buffered I/O on the real access pattern — profile via perf-design.

package/skills/perf-scout/references/memory-and-data-locality.md

@@ -0,0 +1,137 @@
+# Memory & Data Locality — Perf-Scout Strategy Lens
+
+> **When to load this lens**: CPU-bound hot paths, large object graphs, per-element
+> processing, arrays/collections of records, pointer-heavy traversal, allocation
+> churn.
+>
+> **Where these ideas come from**: data-oriented design (game engines, Mike
+> Acton), HPC, and database storage engines — plus the hard truth that a main-
+> memory access can cost ~50-100× an L1 hit (L1 ~1-5 cycles vs DRAM ~100-200
+> cycles), so *how data is laid out in memory often matters more than the
+> instructions over it*. 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)
+- Arrays/lists of heap-allocated objects (array of pointers) iterated in a hot loop.
+- Hot loops that touch one or two fields of a large struct/object per element.
+- Pointer chasing: linked lists, trees, graphs walked per element on a hot path.
+- Frequent small allocations/frees inside a loop; high GC/allocator pressure.
+- Wide structs with mixed hot and cold fields accessed together.
+- Multi-threaded code mutating adjacent fields/counters (false-sharing risk).
+- Random-access patterns over large arrays (cache/TLB-miss prone).
+- Large working sets (multi-GB) with random access — TLB-pressure prone.
+- Multi-socket servers where threads may touch memory pinned to a remote NUMA node.
+
+## Strategies
+
+### 1. Struct-of-Arrays (SoA) instead of Array-of-Structs (AoS)
+- **Borrowed from**: data-oriented design (game engines), GPU/SIMD layouts.
+- **The idea**: store each field in its own contiguous array so a loop that touches one field streams only that field through cache, instead of pulling whole wide records.
+- **Code signals**: hot loop reads `obj.x` for every `obj` in an array of fat objects; vectorizable per-field math.
+- **Speculative win**: fewer cache lines touched per element; enables SIMD; can be multiples on memory-bound loops.
+- **Cost / risk**: invasive layout change; worse when most fields are used together.
+- **Validate by**: cache-miss counters before/after; benchmark the hot loop — perf-design.
+
+### 2. Hot/cold field splitting
+- **Borrowed from**: data-oriented design, database row layout.
+- **The idea**: split frequently-accessed ("hot") fields into a compact struct and move rarely-used ("cold") fields behind a pointer/side table, so hot iteration packs more elements per cache line.
+- **Code signals**: a large struct where the loop uses 2 of 15 fields; "metadata" fields rarely read on the hot path.
+- **Speculative win**: more useful elements per cache line; denser hot scans.
+- **Cost / risk**: indirection to reach cold data; refactor cost.
+- **Validate by**: measure bytes-touched and cache misses on the hot loop.
+
+### 3. Arena / pool / bump allocation
+- **Borrowed from**: game engines, compilers (region allocation), DB buffer pools.
+- **The idea**: allocate many same-lifetime objects from one contiguous arena and free them en masse, replacing scattered malloc/free with pointer bumps.
+- **Code signals**: many short-lived small allocations per frame/request; allocator time in the profile; fragmentation.
+- **Speculative win**: near-free allocation, contiguous layout, one bulk free; less fragmentation and GC pressure.
+- **Cost / risk**: lifetime discipline; misuse → use-after-free or leaks.
+- **Validate by**: allocation-count/alloc-time and locality benchmarks.
+
+### 4. Object pooling / freelist reuse
+- **Borrowed from**: game engines, connection pools.
+- **The idea**: recycle objects from a freelist instead of allocating/collecting them each cycle.
+- **Code signals**: allocate-then-discard of the same type every iteration; GC pauses correlated with churn.
+- **Speculative win**: removes per-iteration allocation and GC pressure.
+- **Cost / risk**: must reset reused state fully; pool sizing; lifetime bugs.
+- **Validate by**: allocations/op and GC-pause metrics.
+
+### 5. Eliminate pointer chasing (flatten / index by offset)
+- **Borrowed from**: cache-aware data structures, ECS storage.
+- **The idea**: replace pointer-linked structures with contiguous arrays indexed by integer handles (e.g. store a tree/graph in arrays, reference children by index), so traversal streams memory.
+- **Code signals**: linked lists/trees/graphs walked on a hot path; each step dereferences a fresh heap node.
+- **Speculative win**: prefetch-friendly sequential access; far fewer cache/TLB misses.
+- **Cost / risk**: handle invalidation; less ergonomic than pointers.
+- **Validate by**: cache-miss counters; traversal benchmark.
+
+### 6. Pack and align structs
+- **Borrowed from**: systems programming, network protocol design.
+- **The idea**: reorder fields to remove padding, shrink types, and use bitfields/packed enums so more elements fit per cache line; align hot data to cache-line boundaries.
+- **Code signals**: structs with mixed-size fields and visible padding; enums stored as ints.
+- **Speculative win**: smaller working set; more elements per line.
+- **Cost / risk**: misalignment can hurt; packing can add masking cost.
+- **Validate by**: `sizeof`/layout inspection; benchmark.
+
+### 7. Avoid false sharing
+- **Borrowed from**: HPC, lock-free engineering.
+- **The idea**: pad/separate per-thread counters and frequently-written fields onto distinct (typically 64-byte) cache lines so cores writing logically-independent data don't bounce a shared line.
+- **Code signals**: per-thread counters/flags packed in one array or struct; multi-core write-heavy code with surprising scaling loss (more threads = slower).
+- **Speculative win**: removes cache-line ping-pong; could recover most of the lost multi-core scaling on the affected path.
+- **Cost / risk**: memory overhead from padding (~56 bytes/counter on a 64-byte line); padding cold/read-mostly data is wasted.
+- **Validate by**: `perf c2c` cache-line contention profiling; scaling benchmark across thread counts.
+
+### 8. Improve traversal order for locality (tiling/blocking)
+- **Borrowed from**: cache-aware algorithms, image processing, HPC.
+- **The idea**: iterate in memory order (row-major vs column-major), tile/block large traversals into sub-blocks sized to a cache level, and group accesses to the same region. (For machine-portable reuse, see cache-oblivious recursion below.)
+- **Code signals**: 2D arrays/matrices traversed against storage order; large random strides; nested loops with poor reuse.
+- **Speculative win**: sequential access, fewer misses; tiling keeps the working set hot across reuse.
+- **Cost / risk**: loop restructuring; tile-size must be tuned per cache/machine and can age.
+- **Validate by**: cache-miss counters; benchmark across tile sizes.
+
+### 9. Shrink the working set
+- **Borrowed from**: HPC, embedded.
+- **The idea**: use smaller representations (smaller ints, quantized floats, interned/dictionary-encoded values, columnar slices) so more of the live data fits in cache.
+- **Code signals**: 64-bit fields where 16/32 suffice; repeated large strings; wide intermediates.
+- **Speculative win**: more data resident in cache; less bandwidth.
+- **Cost / risk**: precision/range loss; encode/decode overhead.
+- **Validate by**: bandwidth/cache metrics; correctness on the narrowed type.
+
+### 10. Prefetch and batch random access
+- **Borrowed from**: database storage engines, HPC.
+- **The idea**: gather the indices/keys first, sort or group them, then access in a cache/prefetch-friendly order; optionally issue explicit software prefetch hints (`__builtin_prefetch`) a few iterations ahead where the access pattern is known but the hardware prefetcher can't see it.
+- **Code signals**: random gather over a big array/table driven by an unsorted key list; pointer-chasing loops the hardware prefetcher can't follow.
+- **Speculative win**: turns random misses into more predictable access; sorted-gather and ahead-of-time prefetch might hide much of the miss latency.
+- **Cost / risk**: extra sort/gather step; software prefetch is fragile — if the hardware prefetcher already covers the pattern it adds overhead and can be *slower*, and pointer-chains serialize, limiting prefetch depth.
+- **Validate by**: benchmark sorted-gather vs. random and with/without prefetch hints; cache-miss counters.
+
+### 11. Copy-on-write / share immutable data
+- **Borrowed from**: functional data structures, OS page management.
+- **The idea**: share immutable buffers/strings/slices instead of deep-copying; copy only on mutation.
+- **Code signals**: defensive deep copies of large data passed around read-only.
+- **Speculative win**: removes large copies and the allocations behind them.
+- **Cost / risk**: aliasing bugs if mutation sneaks in; needs clear ownership.
+- **Validate by**: count/size of copies eliminated; benchmark.
+
+### 12. Cache-oblivious recursive blocking
+- **Borrowed from**: cache-oblivious algorithms (Leiserson/Prokop, MIT) — distinct from hand-tuned tiling.
+- **The idea**: recursively subdivide a problem (matrix multiply, transpose, scans) until sub-blocks fit some cache level; the divide-and-conquer structure gets good reuse at *every* cache level without hard-coding a tile size for a specific machine.
+- **Code signals**: large dense linear-algebra / grid traversals; a tiled loop whose tile size is tuned per-machine and ages badly.
+- **Speculative win**: portable locality across cache levels and CPUs; could approach tuned-tiling reuse without per-target tuning.
+- **Cost / risk**: recursion overhead at small sizes (needs a base-case cutoff); harder to read than a flat loop.
+- **Validate by**: cache-miss counters at L2/L3; benchmark vs. flat and hand-tiled loops across machines.
+
+### 13. Huge pages to cut TLB misses
+- **Borrowed from**: database engines, HPC, OS memory management.
+- **The idea**: back large hot allocations with 2 MB huge pages (or `madvise`/THP) so each TLB entry maps far more memory — a 2 MB page covers 512× the address space of a 4 KB page, shrinking page-walk overhead on large working sets.
+- **Code signals**: multi-GB working set with broad/random access; profile shows `dTLB-load-misses` or page-walk cycles high.
+- **Speculative win**: fewer TLB misses and page walks; a page walk is much costlier than a TLB hit, and its cost varies widely with page-walk-cache and cache/memory residency (so measure it rather than assuming a fixed cycle count). Candidate gain on TLB-bound large-footprint loops.
+- **Cost / risk**: not universal — DBs with sparse/random access can *regress* under transparent huge pages; memory waste and allocation latency; needs OS/allocator support.
+- **Validate by**: `perf stat -e dTLB-load-misses,dtlb_load_misses.walk_*`; benchmark with huge pages on vs off.
+
+### 14. NUMA-aware allocation (first-touch / local placement)
+- **Borrowed from**: HPC, multi-socket server engineering.
+- **The idea**: on multi-socket boxes, place each thread's hot data on its own NUMA node — rely on first-touch (the thread that first *writes* a page owns its placement) or explicit `numa_alloc`/`mbind` — so cores read local rather than remote memory.
+- **Code signals**: multi-socket server; data allocated/initialized by one thread then crunched by threads pinned to other sockets; bandwidth-bound parallel loops that scale poorly past one socket.
+- **Speculative win**: remote access costs ~2× latency and ~1.8× less bandwidth than local; localizing could recover much of that on bandwidth-bound paths.
+- **Cost / risk**: requires thread pinning + first-touch discipline; shared/migrating data defeats it; single-socket machines see no benefit.
+- **Validate by**: `numastat` / per-node bandwidth counters; pinned local-vs-remote benchmark — profile via perf-design.

package/skills/perf-scout/references/parallelism-and-vectorization.md

@@ -0,0 +1,126 @@
+# Parallelism & Vectorization — Perf-Scout Strategy Lens
+
+> **When to load this lens**: independent work done sequentially, map/reduce
+> shapes, numeric kernels, idle cores, large batch processing, request fan-out.
+>
+> **Where these ideas come from**: HPC, GPU programming, high-frequency trading,
+> and lock-free systems engineering. Parallelism is powerful but adds real
+> complexity, so the best candidates are *embarrassingly parallel* work or tight
+> numeric loops that vectorize. Every entry is a *candidate* hypothesis, not a
+> proven win. Cite `file:line`, attribute the source, give a validation path.
+> Note for the orchestrator: parallelism usually pays off only after algorithmic,
+> locality, and I/O wins — flag it, but rank honestly against cheaper lenses.
+
+## Detection signals (where this lens might apply — not proof)
+- Loops over independent items processed one at a time (map shape, no cross-iteration dependency).
+- Numeric inner loops over arrays (sums, dot products, element-wise math, filters).
+- Sequential I/O fan-out (N independent requests awaited one after another).
+- Aggregations (sum/count/min/max/group-by) over large datasets.
+- Single-threaded hot path on a multi-core machine; cores idle under load.
+- Heavy per-request CPU work that could pipeline with I/O.
+
+## Strategies
+
+### 1. Data parallelism over independent items
+- **Borrowed from**: map-reduce, GPU SIMT, parallel STL.
+- **The idea**: split an independent-item loop across cores (thread pool, parallel map, rayon/`parallelStream`/`multiprocessing`), then combine.
+- **Code signals**: a pure map over a large collection with no shared mutable state.
+- **Speculative win**: near-linear speedup up to core count for CPU-bound maps.
+- **Cost / risk**: thread/process overhead; false sharing; only wins above a work threshold.
+- **Validate by**: scaling benchmark across thread counts — perf-design.
+
+### 2. SIMD / vectorization
+- **Borrowed from**: HPC, codecs, columnar/vectorized DB execution.
+- **The idea**: process multiple elements per instruction — restructure loops for auto-vectorization, or use explicit intrinsics / portable SIMD (Rust `std::simd` is still nightly-only as of 2025; `wide`/`std::arch` work on stable); pair with SoA layout.
+- **Code signals**: tight numeric loops over contiguous arrays; element-wise transforms; predicate-heavy filters.
+- **Speculative win**: up to lane count (e.g. ~4–8× for f32 on AVX2; AVX-512 rarely reaches the full 16× because of frequency throttling, register pressure, and memory bandwidth).
+- **Cost / risk**: layout-dependent; branch-heavy loops resist vectorization; portability and wider-vector downclocking.
+- **Validate by**: compiler vectorization report (`-fopt-info-vec` / `-Rpass=loop-vectorize`); kernel microbenchmark.
+
+### 3. Concurrent I/O fan-out
+- **Borrowed from**: async runtimes, service meshes.
+- **The idea**: issue N independent I/O calls concurrently (gather/`Promise.all`/`JoinSet`) instead of awaiting them in sequence.
+- **Code signals**: `for item: await fetch(item)` — serial awaits with no dependency between iterations.
+- **Speculative win**: wall time *could* drop from the sum of the calls toward the slowest single call, if the calls are truly independent and the downstream can absorb the concurrency.
+- **Cost / risk**: downstream rate limits; needs bounded concurrency to avoid overload.
+- **Validate by**: end-to-end latency with realistic concurrency caps.
+
+### 4. Pipeline parallelism (overlap stages)
+- **Borrowed from**: CPU pipelines, stream processors, build systems.
+- **The idea**: split a multi-stage process into stages connected by bounded queues so stage k+1 works on item i while stage k works on item i+1 (overlap CPU with I/O especially).
+- **Code signals**: read→transform→write done fully per item; CPU idle during I/O and vice versa.
+- **Speculative win**: throughput rises toward the slowest stage's rate; hides latency.
+- **Cost / risk**: backpressure and queue sizing; harder error handling.
+- **Validate by**: throughput benchmark; per-stage utilization.
+
+### 5. Parallel reduction / tree aggregation
+- **Borrowed from**: HPC reductions, map-reduce combiners.
+- **The idea**: compute partial aggregates per shard/thread, then combine in a tree, instead of a single sequential fold.
+- **Code signals**: sequential `sum`/`count`/`group-by` over a huge dataset.
+- **Speculative win**: parallel speedup on the reduce with associative/commutative ops.
+- **Cost / risk**: requires associativity; floating-point result ordering changes.
+- **Validate by**: scaling benchmark; numeric-stability check for float reductions.
+
+### 6. Lock-free structures / optimistic reads on hot shared state
+- **Borrowed from**: HFT, lock-free systems engineering; seqlocks from the Linux kernel.
+- **The idea**: replace a contended mutex on a hot shared structure with atomics/CAS or a lock-free queue. For read-mostly state, a *seqlock* lets readers retry optimistically without taking a lock (writers still serialize via an embedded lock) — note this is optimistic, not lock-free/wait-free in the strict sense.
+- **Code signals**: a single hot mutex showing up as contention; many threads hammering one counter/queue; a read-mostly value guarded by a lock.
+- **Speculative win**: *might* remove lock contention and context-switch stalls under load; readers may avoid blocking entirely.
+- **Cost / risk**: very high — true lock-free code is subtle (ABA, memory ordering, reclamation); seqlock readers must tolerate retries and must not observe torn writes. Treat as expert-only.
+- **Validate by**: contention/off-CPU profiling; stress tests; model-checking where feasible.
+
+### 7. Sharding to reduce contention
+- **Borrowed from**: concurrent hash maps, striped locks.
+- **The idea**: partition shared state into N independent shards (striped locks, per-core/per-thread accumulators merged later) so writers rarely collide.
+- **Code signals**: one global lock/counter/map under multi-threaded write load.
+- **Speculative win**: contention drops ~1/N; better multi-core scaling.
+- **Cost / risk**: cross-shard operations get costlier; merge step.
+- **Validate by**: scaling benchmark; contention metrics.
+
+### 8. Work-stealing for irregular workloads
+- **Borrowed from**: work-stealing schedulers (originated in Multilisp, formalized by Cilk; today rayon, Tokio, Java fork/join).
+- **The idea**: use a work-stealing pool so idle cores grab tasks from busy ones when per-item cost varies widely.
+- **Code signals**: parallel work with highly uneven item costs causing load imbalance.
+- **Speculative win**: better core utilization than static partitioning.
+- **Cost / risk**: scheduler overhead for tiny tasks; granularity tuning.
+- **Validate by**: utilization and wall-time benchmark vs. static split.
+
+### 9. GPU / accelerator offload
+- **Borrowed from**: GPU computing, ML kernels.
+- **The idea**: move massively-parallel, arithmetic-heavy, regular work (large element-wise/matrix/convolution ops) to a GPU or SIMD accelerator.
+- **Code signals**: huge regular numeric workloads; matrix/tensor math; image/signal processing on CPU.
+- **Speculative win**: order-of-magnitude on suitable kernels.
+- **Cost / risk**: transfer overhead, deployment complexity; only wins when compute ≫ transfer.
+- **Validate by**: kernel benchmark including host↔device transfer.
+
+### 10. Async over blocking for I/O-bound concurrency
+- **Borrowed from**: event-driven servers (nginx, Node, Tokio).
+- **The idea**: replace thread-per-blocking-call with async I/O so one thread handles many in-flight operations, cutting context-switch and stack overhead at high concurrency.
+- **Code signals**: thread-per-request/-connection under high concurrency; many threads blocked in I/O.
+- **Speculative win**: far higher connection/request concurrency per core; less memory.
+- **Cost / risk**: async complexity; a stray blocking call stalls the loop.
+- **Validate by**: load test at target concurrency; off-CPU profiling.
+
+### 11. False-sharing-aware partitioning
+- **Borrowed from**: cache-coherence engineering; LMAX Disruptor's cache-line padding.
+- **The idea**: when threads write to nearby addresses that share a 64-byte cache line (per-thread counters in one array, fields in one struct), pad or align each thread's data to its own line so writes stop ping-ponging the line between cores.
+- **Code signals**: per-thread/per-core slots packed in one contiguous array or struct, each mutated by a different thread; flat scaling or *negative* scaling as threads increase.
+- **Speculative win**: removes coherence traffic on the hot line — candidate for a large jump once a false-sharing line is the bottleneck (reported impacts have ranged from ~25% up to several-fold).
+- **Cost / risk**: padding wastes cache/memory; only helps when false sharing is the actual cause, not true contention.
+- **Validate by**: `perf c2c` (cache-to-cache / HITM) to locate the line; scaling benchmark before/after padding.
+
+### 12. NUMA-aware parallelism
+- **Borrowed from**: HPC and multi-socket database/server tuning.
+- **The idea**: on multi-socket / multi-NUMA-node machines, pin threads near the memory they touch (first-touch allocation, `numactl`, affinity) so hot data stays in the local node instead of paying cross-node access latency.
+- **Code signals**: a parallel workload that scales within one socket but stalls or regresses across sockets; large shared buffers allocated on one node and read by all.
+- **Speculative win**: cuts remote-memory latency on cross-socket paths; better scaling past one NUMA node.
+- **Cost / risk**: placement is platform-specific and brittle; no benefit on single-socket hardware; can hurt if it fights the OS scheduler.
+- **Validate by**: NUMA-local vs default scaling benchmark; `numastat` / remote-access counters.
+
+### 13. Match the queue to the producer/consumer count
+- **Borrowed from**: lock-free systems engineering; LMAX Disruptor; SPSC/MPSC/SPMC queue families.
+- **The idea**: a queue hand-off forced through a general MPMC structure when the real shape is single-producer/single-consumer (or single-consumer) can switch to a specialized SPSC/MPSC ring buffer with far less synchronization — SPSC needs almost none.
+- **Code signals**: a general concurrent/locking queue on a hot hand-off path whose actual producer/consumer counts are fixed and small.
+- **Speculative win**: cheaper enqueue/dequeue and less contention than a fully general queue on that path.
+- **Cost / risk**: specialized queues have stricter usage contracts; wrong producer/consumer assumptions corrupt data; FIFO may relax.
+- **Validate by**: throughput/latency microbenchmark of the hand-off; contention profiling under target load.

package/skills/perf-scout/references/parked-item-template.md

@@ -0,0 +1,117 @@
+# Parked Perf-Scout Idea Template
+
+> Used by `perf-scout` to park each candidate idea into `.work/backlog/<id>.md`.
+> These are **speculative ideas**, not findings — the frontmatter and body keep
+> that framing. The user elevates anything worth pursuing via
+> `/agile-workflow:scope`, or hands it to `/agile-workflow:perf-design` to measure
+> and validate.
+
+## File location
+
+Parked ideas go to `.work/backlog/<id>.md`. By default only **Investigate-first**
+and **Worth-a-look** ideas are parked — long-shots stay in the report so the
+backlog doesn't fill with speculative noise (pass `--park-all` to park every
+tier). Ideas are investigation candidates, never release blockers — there is no
+active-tier or gate path out of perf-scout. The user chooses what to promote.
+
+## ID convention
+
+`perf-scout-<short-slug>` — slug describes the idea briefly (kebab-case, ≤ 40
+chars after the prefix). On collision, suffix `-2`, `-3`.
+
+Examples:
+- `perf-scout-soa-particle-buffer`
+- `perf-scout-n-plus-1-in-order-loader`
+- `perf-scout-bloom-filter-before-blob-fetch`
+- `perf-scout-hll-distinct-visitors`
+
+## Frontmatter + body template
+
+```yaml
+---
+id: perf-scout-<short-slug>
+created: YYYY-MM-DD            # today's local date
+tags: [perf, idea, <lens-tag>]
+idea_origin: scout            # how this entered the backlog (distinguishes from user-parked ideas)
+idea_lens: algorithmic | memory-locality | parallelism | gpu | caching | io-batching | distributed | game-engine | database-internals | compiler-runtime | approximation
+idea_borrowed_from: <source domain — e.g. "LSM trees", "game-engine ECS", "GPU coalescing">
+idea_priority: investigate-first | worth-a-look | long-shot
+idea_location: <file>:<line>  # canonical location for idempotency
+idea_source: scout | peer-<agent> | peer-fallback   # who generated it
+---
+
+# <one-line idea title>
+
+**Location**: `<file>:<line>` · **Lens**: <lens> · **Borrowed from**: <domain> · **Priority**: <tier>
+**Leverage**: <High|Med|Low> · **Applicability**: <Likely|Plausible|Speculative> · **Cost**: <Low|Med|High>
+
+> ⚠️ Unvalidated hypothesis — no measurement has been done. This is a candidate to
+> investigate, not a proven win.
+
+**The idea**: <2-4 sentences: the specific transform to try here, and the domain technique it borrows.>
+
+**Why it might help**: <the speculative mechanism — "might", never "will".>
+
+**Validate by**: <how to confirm: the metric to measure / benchmark to write / "profile via /agile-workflow:perf-design".>
+
+**Risk**: <one line — correctness, complexity, memory, or behavior-change concern.>
+```
+
+## Lens tag mapping
+
+| Lens | `idea_lens` value | tag |
+|---|---|---|
+| Algorithmic & data structures | `algorithmic` | `algorithmic` |
+| Memory & data locality | `memory-locality` | `memory` |
+| Parallelism & vectorization | `parallelism` | `parallelism` |
+| GPU & accelerators | `gpu` | `gpu` |
+| Caching & memoization | `caching` | `caching` |
+| I/O & batching | `io-batching` | `io` |
+| Distributed systems | `distributed` | `distributed` |
+| Game-engine & realtime | `game-engine` | `realtime` |
+| Database & storage internals | `database-internals` | `storage` |
+| Compiler, runtime & language | `compiler-runtime` | `runtime` |
+| Approximation & precomputation | `approximation` | `approximation` |
+
+All carry the umbrella `perf` and `idea` tags. Optionally add `investigate-first`
+to `tags:` for top-tier ideas so `grep -l "investigate-first" .work/backlog/`
+surfaces them fast.
+
+## Idempotency (re-run protection)
+
+Before parking, index existing parked ideas:
+
+```bash
+grep -rl "^idea_origin: scout$" .work/backlog/ 2>/dev/null | while read -r f; do
+  loc=$(grep -m1 '^idea_location:' "$f" | awk '{print $2}')
+  lens=$(grep -m1 '^idea_lens:' "$f" | awk '{print $2}')
+  [ -n "$loc" ] && echo "$loc $lens $f"
+done > /tmp/perfscout-existing.txt
+```
+
+For each new idea, check the (`file:line`, `idea_lens`) pair against the index. If
+present, **skip** — don't re-park. Two different lenses proposing different
+transforms at the same site are distinct ideas; keep both. Tally the skip count
+for the report.
+
+## Rules
+
+- One idea = one parked file. No bundling (but cluster-level "rethink this layer"
+  ideas are themselves a single idea and park as one file).
+- `idea_origin: scout` is required — distinguishes perf-scout ideas from
+  user-parked ideas (no `idea_origin`).
+- `idea_location` is required — drives idempotency.
+- The ⚠️ unvalidated-hypothesis line is required in every body. It's the honesty
+  contract: these files will be skimmed out of context later, and nothing here
+  should read as a confirmed win.
+- Keep the body tight. Deep analysis lives in `perf-scout-report.md`; backlog
+  files get skimmed.
+- After parking all ideas, commit in one commit:
+  `perf-scout: park <N> ideas (<scope>)`. Use explicit paths, never `git add -A`,
+  if the working tree was already dirty.
+
+## Opt-out
+
+If invoked with `--no-park`, skip this phase entirely. Write only the report and
+note the skipped count in its summary, so it's transparent the substrate was
+bypassed.