cpu-cache-and-numalisted
Install: claude install-skill robsonkades/agent-skills
# CPU Cache and NUMA
## Purpose
Explain hardware-locality failures that blocking-oriented evidence can miss. False sharing
can degrade throughput without monitor contention or a dedicated JFR event, but cache misses,
coherence traffic, CPU saturation and scaling curves still leave evidence. Treat it as a
hypothesis to falsify, not the default explanation for poor scaling.
## Workflow
1. **Measure the scaling curve**: throughput, p99, CPU, allocation and synchronization from
one thread through the production concurrency range. Efficiency is descriptive; there is
no universal 0.5 entry threshold.
2. **Check the signature.** Throughput that worsens as writers are added is consistent with
coherence, but also with locks, queueing, GC, bandwidth saturation, scheduler overhead or
a downstream limit. Use competing hypotheses.
3. **Rule out lock contention and true sharing first** — see the distinction table in
`references/false-sharing.md`. JFR can expose qualifying blocking events; it has no dedicated
false-sharing event, and missing lock events do not rule out spinning or below-threshold waits.
4. **Measure relative field layout with JOL**; offsets do not prove absolute cache-line placement.
5. **Measure coherence on supported hardware.** Prefer `perf c2c`, HITM/cache-to-cache or
vendor PMU events when available; LLC misses alone do not prove false sharing. Normalize
against the application's own baseline and retain event support/scaling warnings.
6. **V