agy-superpowers 5.1.4 → 5.1.5

package/template/agent/skills/rust-developer/references/rust-rules/opt-simd-portable.md

@@ -0,0 +1,144 @@
+# opt-simd-portable
+
+> Use portable SIMD for vectorized operations across architectures
+
+## Why It Matters
+
+SIMD (Single Instruction, Multiple Data) processes multiple values per instruction—4x, 8x, or more speedup for suitable algorithms. Rust's portable SIMD (nightly) and crates like `wide` provide cross-platform vectorization without architecture-specific intrinsics. For stable Rust, let LLVM auto-vectorize or use platform-specific crates.
+
+## Autovectorization (Stable)
+
+```rust
+// LLVM often vectorizes simple patterns automatically
+fn sum(data: &[f32]) -> f32 {
+    data.iter().sum()  // May vectorize to SIMD
+}
+
+fn add_arrays(a: &[f32], b: &[f32], out: &mut [f32]) {
+    for ((x, y), o) in a.iter().zip(b).zip(out.iter_mut()) {
+        *o = x + y;  // Often vectorizes
+    }
+}
+
+// Help autovectorization:
+// 1. Use iterators over indexing
+// 2. Avoid early exits in loops
+// 3. Use chunks_exact for aligned access
+```
+
+## Portable SIMD (Nightly)
+
+```rust
+#![feature(portable_simd)]
+use std::simd::*;
+
+fn sum_simd(data: &[f32]) -> f32 {
+    let (prefix, middle, suffix) = data.as_simd::<8>();
+    
+    // Handle unaligned prefix
+    let mut sum = prefix.iter().sum::<f32>();
+    
+    // SIMD loop - 8 floats at a time
+    let mut simd_sum = f32x8::splat(0.0);
+    for chunk in middle {
+        simd_sum += *chunk;
+    }
+    sum += simd_sum.reduce_sum();
+    
+    // Handle unaligned suffix
+    sum += suffix.iter().sum::<f32>();
+    
+    sum
+}
+
+fn dot_product(a: &[f32], b: &[f32]) -> f32 {
+    assert_eq!(a.len(), b.len());
+    
+    let (a_pre, a_mid, a_suf) = a.as_simd::<8>();
+    let (b_pre, b_mid, b_suf) = b.as_simd::<8>();
+    
+    let scalar: f32 = a_pre.iter().zip(b_pre).map(|(x, y)| x * y).sum();
+    
+    let mut simd_sum = f32x8::splat(0.0);
+    for (av, bv) in a_mid.iter().zip(b_mid) {
+        simd_sum += *av * *bv;
+    }
+    
+    let suffix: f32 = a_suf.iter().zip(b_suf).map(|(x, y)| x * y).sum();
+    
+    scalar + simd_sum.reduce_sum() + suffix
+}
+```
+
+## wide Crate (Stable)
+
+```rust
+use wide::*;
+
+fn process_simd(data: &mut [f32]) {
+    // Process 8 floats at a time
+    for chunk in data.chunks_exact_mut(8) {
+        let v = f32x8::from(chunk);
+        let result = v * f32x8::splat(2.0) + f32x8::splat(1.0);
+        chunk.copy_from_slice(&result.to_array());
+    }
+}
+
+fn blend_images(a: &[u8], b: &[u8], alpha: f32, out: &mut [u8]) {
+    let alpha_v = f32x8::splat(alpha);
+    let one_minus = f32x8::splat(1.0 - alpha);
+    
+    for ((a_chunk, b_chunk), out_chunk) in 
+        a.chunks_exact(8).zip(b.chunks_exact(8)).zip(out.chunks_exact_mut(8)) 
+    {
+        let av = f32x8::from([
+            a_chunk[0] as f32, a_chunk[1] as f32, /* ... */
+        ]);
+        let bv = f32x8::from([
+            b_chunk[0] as f32, b_chunk[1] as f32, /* ... */
+        ]);
+        
+        let result = av * one_minus + bv * alpha_v;
+        // Convert back to u8...
+    }
+}
+```
+
+## Platform-Specific (When Needed)
+
+```rust
+#[cfg(target_arch = "x86_64")]
+use std::arch::x86_64::*;
+
+#[cfg(target_arch = "x86_64")]
+#[target_feature(enable = "avx2")]
+unsafe fn sum_avx2(data: &[f32]) -> f32 {
+    let mut sum = _mm256_setzero_ps();
+    
+    for chunk in data.chunks_exact(8) {
+        let v = _mm256_loadu_ps(chunk.as_ptr());
+        sum = _mm256_add_ps(sum, v);
+    }
+    
+    // Horizontal sum
+    let high = _mm256_extractf128_ps(sum, 1);
+    let low = _mm256_castps256_ps128(sum);
+    let sum128 = _mm_add_ps(high, low);
+    // ... continue reduction
+}
+```
+
+## Choosing an Approach
+
+| Approach | Stability | Portability | Control |
+|----------|-----------|-------------|---------|
+| Autovectorization | Stable | Excellent | Low |
+| `wide` crate | Stable | Good | Medium |
+| Portable SIMD | Nightly | Excellent | High |
+| Intrinsics | Stable | None | Maximum |
+
+## See Also
+
+- [opt-target-cpu](./opt-target-cpu.md) - Enable SIMD features
+- [opt-bounds-check](./opt-bounds-check.md) - Unchecked access for SIMD
+- [perf-profile-first](./perf-profile-first.md) - Identify vectorization opportunities

package/template/agent/skills/rust-developer/references/rust-rules/opt-target-cpu.md

@@ -0,0 +1,154 @@
+# opt-target-cpu
+
+> Use `target-cpu=native` for maximum performance on known deployment targets
+
+## Why It Matters
+
+By default, Rust compiles for a generic x86-64 baseline (roughly Sandy Bridge era). Modern CPUs have SIMD extensions (AVX2, AVX-512), improved instructions, and micro-architectural optimizations that go unused. `target-cpu=native` enables all features of your current CPU, potentially unlocking significant speedups.
+
+## Bad
+
+```toml
+# Cargo.toml - compiles for generic x86-64
+[profile.release]
+# No target-cpu specified
+# Binary works everywhere but uses only SSE2
+```
+
+## Good
+
+```toml
+# .cargo/config.toml - for known deployment target
+[build]
+rustflags = ["-C", "target-cpu=native"]
+
+# Or specific CPU for cross-compilation
+# rustflags = ["-C", "target-cpu=skylake"]
+```
+
+## Via Environment
+
+```bash
+# Build with native optimizations
+RUSTFLAGS="-C target-cpu=native" cargo build --release
+
+# Check what features are enabled
+rustc --print cfg -C target-cpu=native | grep target_feature
+```
+
+## Common Target CPUs
+
+```bash
+# x86-64 targets
+target-cpu=native          # Current machine
+target-cpu=x86-64          # Baseline (SSE2)
+target-cpu=x86-64-v2       # SSE4.2, POPCNT
+target-cpu=x86-64-v3       # AVX2, BMI2
+target-cpu=x86-64-v4       # AVX-512
+
+# Intel specific
+target-cpu=skylake         # 6th gen Core
+target-cpu=alderlake       # 12th gen Core
+
+# AMD specific
+target-cpu=znver3          # Zen 3
+target-cpu=znver4          # Zen 4
+
+# ARM
+target-cpu=apple-m1        # Apple Silicon
+target-cpu=neoverse-n1     # AWS Graviton2
+```
+
+## Feature Detection at Runtime
+
+```rust
+// For portable binaries that use native features when available
+#[cfg(target_arch = "x86_64")]
+fn process_fast(data: &[u8]) -> u64 {
+    if is_x86_feature_detected!("avx2") {
+        unsafe { process_avx2(data) }
+    } else if is_x86_feature_detected!("sse4.2") {
+        unsafe { process_sse42(data) }
+    } else {
+        process_generic(data)
+    }
+}
+
+#[target_feature(enable = "avx2")]
+unsafe fn process_avx2(data: &[u8]) -> u64 {
+    // AVX2 optimized implementation
+}
+```
+
+## Multi-Architecture Builds
+
+```bash
+# Build multiple binaries
+RUSTFLAGS="-C target-cpu=x86-64" cargo build --release
+mv target/release/app target/release/app-generic
+
+RUSTFLAGS="-C target-cpu=x86-64-v3" cargo build --release
+mv target/release/app target/release/app-avx2
+
+# Select at runtime
+if supports_avx2; then
+    ./app-avx2
+else
+    ./app-generic
+fi
+```
+
+## Cargo Configuration
+
+```toml
+# .cargo/config.toml
+
+# Native builds for development
+[target.x86_64-unknown-linux-gnu]
+rustflags = ["-C", "target-cpu=native"]
+
+# AWS deployment (Graviton2)
+[target.aarch64-unknown-linux-gnu]
+rustflags = ["-C", "target-cpu=neoverse-n1"]
+
+# Intel server deployment
+[target.x86_64-unknown-linux-gnu.deployment]
+rustflags = ["-C", "target-cpu=skylake-avx512"]
+```
+
+## What Changes
+
+```rust
+// With AVX2 enabled:
+// - 256-bit SIMD operations
+// - Better autovectorization
+// - FMA (fused multiply-add)
+// - BMI (bit manipulation)
+
+// Example: sum of squares
+fn sum_squares(data: &[f64]) -> f64 {
+    data.iter().map(|x| x * x).sum()
+}
+// Generic: scalar loop
+// AVX2: processes 4 f64s per iteration
+```
+
+## Checking Enabled Features
+
+```bash
+# What's enabled for native?
+rustc --print cfg -C target-cpu=native | grep feature
+
+# Compare generic vs native
+rustc --print cfg -C target-cpu=x86-64 | grep feature
+rustc --print cfg -C target-cpu=native | grep feature
+
+# View generated assembly
+cargo asm --rust --release my_crate::hot_function
+```
+
+## See Also
+
+- [opt-lto-release](./opt-lto-release.md) - Combine with LTO
+- [opt-simd-portable](./opt-simd-portable.md) - Portable SIMD
+- [opt-codegen-units](./opt-codegen-units.md) - Single codegen unit

package/template/agent/skills/rust-developer/references/rust-rules/own-arc-shared.md

@@ -0,0 +1,141 @@
+# own-arc-shared
+
+> Use `Arc<T>` for thread-safe shared ownership
+
+## Why It Matters
+
+`Arc` (Atomic Reference Counted) provides shared ownership across threads. Unlike `Rc`, its reference count is updated atomically, making it safe for concurrent access. Use it when multiple threads need to read the same data.
+
+## Bad
+
+```rust
+use std::rc::Rc;
+use std::thread;
+
+let data = Rc::new(vec![1, 2, 3]);
+let data_clone = Rc::clone(&data);
+
+// ERROR: Rc cannot be sent between threads safely
+thread::spawn(move || {
+    println!("{:?}", data_clone);
+});
+```
+
+## Good
+
+```rust
+use std::sync::Arc;
+use std::thread;
+
+let data = Arc::new(vec![1, 2, 3]);
+let data_clone = Arc::clone(&data);
+
+thread::spawn(move || {
+    println!("{:?}", data_clone);  // Safe!
+});
+
+println!("{:?}", data);  // Original still accessible
+```
+
+## Arc with Mutex for Mutable Shared State
+
+```rust
+use std::sync::{Arc, Mutex};
+use std::thread;
+
+let counter = Arc::new(Mutex::new(0));
+let mut handles = vec![];
+
+for _ in 0..10 {
+    let counter = Arc::clone(&counter);
+    let handle = thread::spawn(move || {
+        let mut num = counter.lock().unwrap();
+        *num += 1;
+    });
+    handles.push(handle);
+}
+
+for handle in handles {
+    handle.join().unwrap();
+}
+
+println!("Result: {}", *counter.lock().unwrap());
+```
+
+## Arc vs Rc Decision Tree
+
+```
+Need shared ownership?
+├── No → Use owned value or references
+└── Yes → Will it cross thread boundaries?
+    ├── No → Use Rc<T> (cheaper, no atomic ops)
+    └── Yes → Use Arc<T>
+        └── Need mutation?
+            ├── No → Arc<T> is enough
+            └── Yes → Arc<Mutex<T>> or Arc<RwLock<T>>
+```
+
+## Common Patterns
+
+```rust
+use std::sync::Arc;
+
+// Shared configuration (read-only)
+struct AppConfig {
+    database_url: String,
+    max_connections: u32,
+}
+
+fn setup_workers(config: Arc<AppConfig>) {
+    for i in 0..4 {
+        let config = Arc::clone(&config);
+        std::thread::spawn(move || {
+            println!("Worker {} using db: {}", i, config.database_url);
+        });
+    }
+}
+
+// Shared cache with interior mutability
+use std::sync::RwLock;
+use std::collections::HashMap;
+
+type Cache = Arc<RwLock<HashMap<String, String>>>;
+
+fn get_cached(cache: &Cache, key: &str) -> Option<String> {
+    cache.read().unwrap().get(key).cloned()
+}
+
+fn set_cached(cache: &Cache, key: String, value: String) {
+    cache.write().unwrap().insert(key, value);
+}
+```
+
+## Performance Considerations
+
+```rust
+// Arc::clone is cheap - just increments atomic counter
+let a = Arc::new(large_data);
+let b = Arc::clone(&a);  // Fast! No data copied
+
+// But atomic operations have overhead vs Rc
+// Use Rc in single-threaded contexts for better performance
+
+// Avoid cloning Arc in hot loops if possible
+// Bad:
+for item in items {
+    let arc = Arc::clone(&shared);  // Atomic op each iteration
+    process(arc, item);
+}
+
+// Better: Clone once outside loop if possible
+let arc = Arc::clone(&shared);
+for item in items {
+    process(&arc, item);  // Pass reference
+}
+```
+
+## See Also
+
+- [own-rc-single-thread](own-rc-single-thread.md) - Use Rc for single-threaded sharing
+- [own-mutex-interior](own-mutex-interior.md) - Use Mutex for interior mutability
+- [async-clone-before-await](async-clone-before-await.md) - Clone Arc before await points

package/template/agent/skills/rust-developer/references/rust-rules/own-borrow-over-clone.md

@@ -0,0 +1,95 @@
+# own-borrow-over-clone
+
+> Prefer `&T` borrowing over `.clone()`
+
+## Why It Matters
+
+Cloning allocates new memory and copies data, while borrowing is free. Unnecessary clones can significantly impact performance, especially in hot paths or with large data structures.
+
+## Bad
+
+```rust
+fn process(data: &String) {
+    let local = data.clone();  // Unnecessary allocation!
+    println!("{}", local);
+}
+
+fn count_words(text: &String) -> usize {
+    let owned = text.clone();  // Why clone just to read?
+    owned.split_whitespace().count()
+}
+
+// Clone in a loop - multiplied cost
+fn process_all(items: &[String]) {
+    for item in items {
+        let copy = item.clone();  // N allocations!
+        handle(&copy);
+    }
+}
+```
+
+## Good
+
+```rust
+fn process(data: &str) {  // Accept &str, more flexible
+    println!("{}", data);  // No allocation needed
+}
+
+fn count_words(text: &str) -> usize {
+    text.split_whitespace().count()  // Just borrow
+}
+
+// Borrow in a loop - zero allocations
+fn process_all(items: &[String]) {
+    for item in items {
+        handle(item);  // Pass reference
+    }
+}
+```
+
+## When Clone Is Acceptable
+
+```rust
+// 1. Need owned data for storage
+struct Cache {
+    data: HashMap<String, String>,
+}
+
+impl Cache {
+    fn insert(&mut self, key: &str, value: &str) {
+        // Clone needed - we're storing owned data
+        self.data.insert(key.to_string(), value.to_string());
+    }
+}
+
+// 2. Need to send across threads
+fn spawn_worker(data: &Config) {
+    let owned = data.clone();  // Clone needed for 'static
+    std::thread::spawn(move || {
+        use_config(owned);
+    });
+}
+
+// 3. Copy types (no heap allocation)
+let x: i32 = 42;
+let y = x;  // Copy, not clone - this is fine
+```
+
+## Evidence
+
+From ripgrep's codebase - uses `Cow` to avoid clones:
+```rust
+// https://github.com/BurntSushi/ripgrep/blob/master/crates/globset/src/pathutil.rs
+pub(crate) fn file_name<'a>(path: &Cow<'a, [u8]>) -> Option<Cow<'a, [u8]>> {
+    match *path {
+        Cow::Borrowed(path) => Cow::Borrowed(&path[last_slash..]),
+        Cow::Owned(ref path) => Cow::Owned(path.clone()),
+    }
+}
+```
+
+## See Also
+
+- [own-slice-over-vec](own-slice-over-vec.md) - Accept slices instead of references to collections
+- [own-cow-conditional](own-cow-conditional.md) - Use Cow for conditional ownership
+- [mem-clone-from](mem-clone-from.md) - Reuse allocations when cloning

package/template/agent/skills/rust-developer/references/rust-rules/own-clone-explicit.md

@@ -0,0 +1,135 @@
+# own-clone-explicit
+
+> Use explicit `Clone` for types where copying has meaningful cost
+
+## Why It Matters
+
+Unlike `Copy` which is implicit and "free," `Clone` requires an explicit `.clone()` call, signaling that duplication has a cost. This makes heap allocations and deep copies visible in code, helping developers reason about performance. Types with heap data (`String`, `Vec`, `Box`) should implement `Clone` but not `Copy`.
+
+## Bad
+
+```rust
+// Hiding expensive operations
+fn process_data(data: Vec<u32>) -> Vec<u32> {
+    let backup = data; // Moved, not copied - but unclear at call site
+    transform(backup)
+}
+
+let my_data = vec![1, 2, 3, 4, 5];
+let result = process_data(my_data);
+// my_data is moved - surprise if you expected it to still exist
+```
+
+## Good
+
+```rust
+fn process_data(data: Vec<u32>) -> Vec<u32> {
+    let backup = data; 
+    transform(backup)
+}
+
+let my_data = vec![1, 2, 3, 4, 5];
+let result = process_data(my_data.clone()); // Explicit: "I know this allocates"
+// my_data still available
+
+// Or better - take reference if you don't need ownership
+fn process_data_ref(data: &[u32]) -> Vec<u32> {
+    transform(data)
+}
+let result = process_data_ref(&my_data); // No clone needed
+```
+
+## Custom Clone Implementation
+
+For types with mixed cheap/expensive fields, implement `Clone` manually:
+
+```rust
+#[derive(Debug)]
+struct Document {
+    id: u64,              // Cheap to copy
+    content: String,      // Expensive to clone
+    metadata: Metadata,   // Moderate cost
+}
+
+impl Clone for Document {
+    fn clone(&self) -> Self {
+        Self {
+            id: self.id,
+            content: self.content.clone(),
+            metadata: self.metadata.clone(),
+        }
+    }
+    
+    // Optimization: reuse existing allocations
+    fn clone_from(&mut self, source: &Self) {
+        self.id = source.id;
+        self.content.clone_from(&source.content); // Reuses capacity
+        self.metadata.clone_from(&source.metadata);
+    }
+}
+```
+
+## clone_from Optimization
+
+`clone_from` can reuse existing allocations:
+
+```rust
+let mut buffer = String::with_capacity(1000);
+
+// Bad: drops old allocation, creates new one
+buffer = source.clone();
+
+// Good: reuses existing capacity if sufficient
+buffer.clone_from(&source);
+```
+
+## Derive vs Manual Clone
+
+```rust
+// Derive when all fields need cloning
+#[derive(Clone)]
+struct Simple {
+    data: Vec<u8>,
+    name: String,
+}
+
+// Manual when you need special behavior
+struct CachedValue {
+    value: i32,
+    cache: RefCell<Option<ExpensiveComputation>>,
+}
+
+impl Clone for CachedValue {
+    fn clone(&self) -> Self {
+        Self {
+            value: self.value,
+            cache: RefCell::new(None), // Don't clone cache, let it rebuild
+        }
+    }
+}
+```
+
+## When to Avoid Clone
+
+```rust
+// Instead of cloning, consider:
+
+// 1. References
+fn process(data: &MyType) { } // Borrow instead of clone
+
+// 2. Cow for conditional cloning
+fn process(data: Cow<'_, str>) { } // Clone only if mutation needed
+
+// 3. Arc for shared ownership
+let shared = Arc::new(expensive_data);
+let handle = shared.clone(); // Cheap: just increments counter
+
+// 4. Passing by value when caller is done with it
+fn consume(data: MyType) { } // Caller moves, no clone
+```
+
+## See Also
+
+- [own-copy-small](./own-copy-small.md) - When implicit Copy is appropriate
+- [own-cow-conditional](./own-cow-conditional.md) - Avoiding clones with Cow
+- [mem-clone-from](./mem-clone-from.md) - Optimizing repeated clones