agy-superpowers 5.2.2 → 5.2.4

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

@@ -1,144 +0,0 @@
-# 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

@@ -1,154 +0,0 @@
-# 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

@@ -1,141 +0,0 @@
-# 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

@@ -1,95 +0,0 @@
-# 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

@@ -1,135 +0,0 @@
-# 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