mechanical-sympathy-and-perf-gate
Skill4 starsChanged 31 days agoMITView on GitHub
Enforces Apple and Google Systems mechanical sympathy, hardware-level cache/memory efficiency, 120Hz (8.3ms) frame budgets, bounded streaming, and empirical benchmark/flamegraph gates. Use when asked to speed up slow code, optimize CPU cache locality, fix 120Hz/60Hz UI frame drops or main-thread jank, eliminate heap allocations in hot loops, prevent OOMs by streaming large payloads, or validate performance optimizations with flamegraphs and benchmarks — even if the user doesn't explicitly say "mechanical sympathy" or "perf gate". Do NOT use for routine CSS color/styling tweaks, static documentation typos, or non-performance functional bug fixes.
In this repository47 other files it gives its agents.
- AGENTS.mdAGENTS.md
- anti-slop-engineeringSkill
- anti-slop-engineeringSkill
- api-ergonomics-and-contract-governorSkill
- apple-craft-and-frame-budgetSkill
- apple-craft-and-interaction-physicsSkill
- asset-provenance-guardSkill
- backprop-guardSkill
- chaos-and-degradation-choreographerSkill
- chromatic-drift-guardSkill
- cognitive-load-and-attention-governorSkill
- comment-budget-guardSkill
- context-window-and-token-economics-architectSkill
- cryptographic-agility-and-secret-lifecycle-gateSkill
- decision-guardSkill
- demock-guardSkill
- design-system-drift-guardSkill
- deterministic-simulation-and-property-testingSkill
- distributed-consensus-and-concurrency-gateSkill
- finops-and-unit-economics-governorSkill
- future-scale-gateSkill
- grumpy-senior-staff-engineerSkill
- honeypot-trap-guardSkill
- house-tell-guardSkill
- install-anti-slopSkill
- llm-eval-and-prompt-injection-fortressSkill
- mandela-guardSkill
- mechanical-sympathy-profilerSkill
- motion-runtime-guardSkill
- observability-and-slo-architectSkill
- observability-and-slo-gateSkill
- paranoid-principal-architectSkill
- pr-boundary-guardSkill
- privacy-and-data-lineage-gateSkill
- re0-handoff-guardSkill
- reduction-guardSkill
- repo-memory-and-invariant-stewardSkill
- root-fix-gateSkill
- safe-evolution-and-rollout-choreographerSkill
- scientific-fault-isolationSkill
- styleseed-guardSkill
- supply-chain-and-sbom-sentinelSkill
- tagore-guardSkill
- type-level-and-ast-slop-gateSkill
- ui-and-copy-disciplineSkill
- verification-oracle-architectSkill
- zero-downtime-migration-gateSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 52
Inspect PostgreSQL
BUFFERS, not just cost estimates: Always run EXPLAIN (ANALYZE, BUFFERS) and verify shared hit vs shared read blocks … - Very specific: line 54
Pre-index quadratic scans: Never nest .find(), .includes(), or .indexOf() inside array loops ($O(N^2)$).
- Very specific: line 55
Epsilon-terminated
requestAnimationFrame: Always terminate continuous animation loops when $|\text{current} - \text{target}| < 10^{-4}$. - Distinctive: line 75
Before modifying a single line of code, adding an index, or introducing a cache, answer these five questions:
- Very specific: line 106
When a durable performance record is warranted, save perf-record.json and audit with:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Skill: Mechanical Sympathy & Performance Gate (Apple & Google Systems Discipline)
Never optimize in the dark, never fight the physical limits of the CPU cache or display compositor, and never accept speculative caching over broken algorithmics. Measure baseline reality first.
Why This Skill Is Needed & Target State
AI coding assistants routinely fall into Speculative Optimization Slop: guessing bottlenecks without profiling, wrapping slow $O(N^2)$ lookups or unindexed database queries in Redis caches (introducing cache stampedes and stale-data bugs), peppering React components with cargo-cult useMemo/useCallback wrappers, and causing severe mobile stutter by animating layout properties (height, top) while violating the 120Hz frame budget.
The target state is Apple & Google Systems Mechanical Sympathy:
- Data-Oriented Design (DOD): Structure memory into contiguous flat buffers (Struct of Arrays) to maximize 64-byte CPU cache line hits, eliminate pointer chasing, and guarantee zero heap allocations in hot loops.
- 120Hz (8.33ms) / 60Hz (16.67ms) Frame Budgets: Reserve at least 4.3ms of headroom per frame for layout and compositing by keeping main-thread JavaScript execution under
4.0ms, eliminating forced synchronous layout thrashing (FastDOM reads before writes), and animating strictly GPU compositor properties (transform,opacity). - Zero-Copy & Streaming Architecture: Stream multi-megabyte/gigabyte payloads in bounded chunks (e.g. 64KB) with backpressure so peak resident memory remains $O(1)$ without whole-payload RAM buffering (
readFileSync,response.text()). - Empirical Benchmark Proof & Flamegraphs: Refuse any optimization claim without reproducible before-and-after numbers (P50, P99 latency, heap allocations, throughput, and PostgreSQL
EXPLAIN (ANALYZE, BUFFERS)buffer hits/reads) proving a $\ge 15%$ P99 latency reduction.
Activation and Boundaries
| Situation | Behavior |
| Speeding up backend loops, numerical compute, vector search, or parsers | Enforce Data-Oriented Design (SoA / TypedArrays), 64-byte cache line packing, and zero-allocation hot paths |
| Authoring or auditing UI animations, gestures, scroll handlers, or canvas rendering | Enforce 120Hz (8.33ms) frame budget, <4ms main-thread script budget, FastDOM separation, and compositor-only motion |
| Processing files, CSV/NDJSON exports, large DB query results, or file uploads | Mandate bounded-chunk streaming with backpressure ($O(1)$ RSS memory); prohibit whole-payload RAM buffering |
| PR claiming "speed improvements", adding Redis/in-memory caches, or adding database indexes | Demand baseline vs post-change flamegraphs and microbenchmarks; apply the Revert-on-Noise gate ($\ge 15%$ improvement) |
| Routine UI styling tweaks, copy edits, or non-performance functional bug fixes | Do not activate; route to anti-slop-engineering |
The Five Absolute Laws
- The Empirical Measurement & Flamegraph Law (Zero Blind Optimization): Modifying code in the name of performance without recorded baseline and post-change telemetry is strictly prohibited. Capture CPU/Heap flamegraphs, P50/P99 latency, and heap allocations (
alloc_bytes/op,allocs/op). If post-change telemetry fails to demonstrate a $\ge 15%$ reduction in P99 latency or a strict decrease in heap allocations or buffer reads while adding code complexity, revert the change. - The Data-Oriented Design & Cache Locality Law (Spatial Locality Over Pointer Chasing): CPUs fetch data in 64-byte cache lines. Monolithic object arrays (Array of Structures / AoS) force pointer chasing across DRAM, stalling the pipeline for 100ns per item. Pack hot attributes into contiguous TypedArrays (Struct of Arrays / SoA) to allow hardware prefetchers to stream memory at bus speed.
- The Zero-Allocation Hot-Path Law (GC Tail-Latency Elimination): Every byte allocated in a hot loop must later be traced and swept by the Garbage Collector, causing unpredictable P99 latency spikes. Pre-allocate collections, mutate accumulators in-place, hoist regex/formatter instances, and ban intermediate array chaining (
.map().filter().reduce()). - The 120Hz (8.33ms) Frame Budget Physics Law: On 120Hz ProMotion displays, the browser has
8.33msper frame. Per-frame JavaScript work on the Main Thread must remain under4.0mswith zero tasks exceeding50ms(Long Tasks). Animate strictly GPU compositor properties (transform,opacity), eliminate forced synchronous layout thrashing, and offload heavy computation to Web Workers. - The Zero-Copy & Bounded Streaming Law ($O(1)$ Memory Over RAM Buffering): Loading whole files or large payloads into RAM (
fs.readFileSync,await response.text(), full array materialization) is a fatal defect that causes OOM process termination. Stream data in bounded chunks with backpressure, and transfer buffer ownership without cloning (ArrayBuffer.transfer(), Transferable Objects).
Invariant Rules
- FastDOM Phase Separation: Separate geometric layout reads (
getBoundingClientRect(),offsetWidth,scrollTop) from style mutations. Perform all reads first, then batch writes inrequestAnimationFrame. - Ban
transition: all: Enumerate explicit compositor properties (transform,opacity). Never animate layout properties (width,height,top,left,margin,padding). - Inspect PostgreSQL
BUFFERS, not just cost estimates: Always runEXPLAIN (ANALYZE, BUFFERS)and verifyshared hitvsshared readblocks and scan selectivity. - Single-pass iteration: Collapse multi-stage array chains (
.filter().map().filter()) into a single-passforloop with index access. - Pre-index quadratic scans: Never nest
.find(),.includes(), or.indexOf()inside array loops ($O(N^2)$); construct an $O(1)$MaporSetbefore the loop. - Epsilon-terminated
requestAnimationFrame: Always terminate continuous animation loops when $|\text{current} - \text{target}| < 10^{-4}$. - Bound stream high-water marks: Explicitly configure chunk buffer sizes (e.g. 64KB) and wire cancellation (
AbortSignal) through stream pipelines. - Transferable worker messages: Pass large
ArrayBufferinstances in the transfer list ([buffer]) to eliminate thread-boundary memory copies. - Eliminate object-spread reducers: Ban
items.reduce((acc, x) => ({ ...acc, [x.id]: x }), {})($O(N^2)$ memory churn) in favor of mutating aMapor pre-allocated object.
Execution Router
| Task Shape | Primary Workflow | Reference Contract |
| Designing compute engines, numerical pipelines, or cache-aligned memory | Design Data-Oriented System | Data-Oriented Design Reference |
| Auditing or fixing 120Hz/60Hz UI frame drops, layout thrashing, or main-thread stalls | Audit & Eliminate Latency Jank | Frame & Latency Budgets Reference |
| Proving performance optimizations, query tuning, or refactoring hot loops | Benchmark & Prove Optimization | Flamegraphs & Benchmarking Reference |
| Durable mechanical sympathy & perf record generation and automated guard audit | Record Contract | scripts/perf_guard.py |
Mandatory Pre-Optimization Interrogation Matrix
Before modifying a single line of code, adding an index, or introducing a cache, answer these five questions:
- The Baseline Proof Check: Where is the baseline flamegraph SVG or benchmark report showing current P50/P99 latency,
alloc_bytes/op, and throughput? If none exists, stop and measure first. - The Memory Locality Check: Is data packed into contiguous TypedArrays to exploit 64-byte CPU cache lines, or is the CPU pointer-chasing across thousands of individual heap objects?
- The Hot-Loop Allocation Check: Does the loop allocate closures, temporary arrays, regexes, or object spreads? How many bytes are allocated per operation?
- The 120Hz Frame Deadline Check: For UI code, does JavaScript execution finish in $< 4.0\text{ms}$? Does any DOM read trigger forced synchronous layout reflow after a write?
- The Bounded Streaming Check: Does peak memory scale as $O(1)$ via bounded streaming, or does the code buffer entire payloads into RAM?
Prohibited Anti-Patterns (Instant Rejection List)
- Unmeasured "Trust-Me" Optimization: Submitting an optimization refactor, cache layer, or index without before-and-after flamegraph or benchmark numbers.
- Whole-File RAM Buffering: Calling
fs.readFileSync,fs.promises.readFile,response.text(), orresponse.arrayBuffer()on unbounded or user-scaled files. - Forced Synchronous Layout Thrashing: Mutating style properties and subsequently reading geometric dimensions (
offsetHeight,getBoundingClientRect()) within the same frame. - CSS
transition: all: Animating layout properties (height,top,margin) instead of GPU compositor properties (transform,opacity). - Quadratic Lookups in Loops: Calling
.find(),.includes(), or.indexOf()inside array iterations instead of building an $O(1)$Map/Set. - Hot-Path Object Spread Reducers: Using
{ ...acc, [k]: v }inside.reduce()on dynamic collections ($O(N^2)$ heap allocation churn). - Synchronous
localStorage/sessionStorage: Blocking the main thread with synchronous stringification inside render or scroll paths.
Required Output & Review Workflow
Structure all performance engineering designs, reviews, and implementations through this 4-phase discipline:
- Baseline Profiling & Flamegraph: Capture and report the baseline measurement (flamegraph profile, P50/P99 latency, heap allocations, and buffer reads).
- Mechanical Sympathy Design: Specify the exact hardware/memory transformation (SoA typed buffers, zero-allocation loop, <4ms frame slice, or bounded streaming).
- Sympathetic Implementation: Emit clean, production-grade code adhering to cache locality, backpressure, and compositor physics.
- Post-Change Verification & Delta Table: Re-run the benchmark under identical conditions, present a side-by-side Before vs After Delta Table, and verify with
scripts/perf_guard.py.
When a durable performance record is warranted, save perf-record.json and audit with:
npx anti-slop-engineering perf audit <record.json> [--source <hot_path.ts>] --json
# or: python3 scripts/perf_guard.py audit <record.json> [--source <hot_path.ts>] --jsonDomain References
- Playbook Suite Overview: Central orchestration index for Apple and Google Systems mechanical sympathy.
- Systems Mechanical Sympathy Playbook: DOD memory packing, cache locality, and zero-copy streams.
- Client Runtime Frame Budget Playbook: 120Hz/60Hz frame budgets, FastDOM read/write batching, and FLIP animations.
- Hardware & Runtime Booby-Traps: Catalog of exact failure mechanics and code remedies.
- Data-Oriented Design & Cache Physics: 64-byte cache lines, SoA layouts, and zero-allocation hot paths.
- Frame & Latency Budgets (120Hz): Compositor pipeline, FastDOM phase separation, and Web Worker offloading.
- Zero-Copy & Streaming Architecture: Bounded streams with backpressure, $O(1)$ RSS, and buffer transfers.
- Flamegraphs & Empirical Benchmarking: Generating flamegraphs,
EXPLAIN BUFFERS, and the Revert-on-Noise gate. - Perf Record Contract: Schema and automated verification rules for
scripts/perf_guard.py.
Failure Taxonomy
| Failure Mode | Observable Signal | Remediation |
| CPU Cache Miss Stalls | High CPU time in loop with low instructions per cycle (IPC) | Migrate from AoS to SoA typed arrays; pack data into 64-byte cache lines |
| GC Tail-Latency Sawtooth | P50 is 2ms but P99 spikes to 180ms during high throughput | Eliminate intermediate .map().filter() chains and object spreads; mutate in-place |
| Layout Thrashing Jank | Frame drops (> 8.33ms on 120Hz displays) during scroll or animation | FastDOM phase separation: batch all geometry reads before style writes |
| Whole-Payload OOM Crash | Worker process killed by kernel during large file export | Replace readFileSync with bounded Web Streams (TransformStream) with backpressure |
| Speculative Caching Slop | Redis cache or useMemo added without baseline measurement | Revert cache; profile root algorithmic or query bottleneck with flamegraph |
Delegated Skills
anti-slop-engineering: Enforce clean-room KISS/DRY/YAGNI gates and test integrity.paranoid-principal-architect: Pair performance optimizations with zero-trust boundary schema parsing, idempotency, and 10M-concurrent-user limits.scientific-fault-isolation: Isolate whether a latency regression originated from a database lock, a commit, or a runtime upgrade using binary search and differential diagnosis.
Completion and Limits
The task is complete when baseline and post-change measurements prove $\ge 15%$ P99 latency reduction or strict allocation/buffer reduction, memory is structured for 64-byte CPU cache locality, UI interactions meet the 120Hz (8.33ms) frame deadline with zero layout thrashing, payloads stream in bounded $O(1)$ memory, and scripts/perf_guard.py reports zero findings. A review may validly output refuse or pause if an optimization is proposed without empirical baseline proof or relies on speculative caching over unmeasured bottlenecks.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

