agy-superpowers 5.1.4 → 5.1.6

package/template/agent/skills/rust-developer/references/rust-rules/opt-pgo-profile.md

@@ -0,0 +1,167 @@
+# opt-pgo-profile
+
+> Use Profile-Guided Optimization (PGO) for maximum performance
+
+## Why It Matters
+
+PGO uses real runtime behavior to guide compiler optimization decisions. By profiling actual workloads, the compiler learns which code paths are hot, optimizing them aggressively while deprioritizing cold paths. This can yield 10-30% performance improvements beyond standard optimizations.
+
+## The PGO Process
+
+1. **Instrument**: Build with profiling instrumentation
+2. **Profile**: Run representative workloads
+3. **Optimize**: Rebuild using collected profile data
+
+## Step-by-Step
+
+```bash
+# Step 1: Build instrumented binary
+RUSTFLAGS="-Cprofile-generate=/tmp/pgo-data" \
+    cargo build --release
+
+# Step 2: Run representative workloads
+./target/release/my_app < test_data_1.txt
+./target/release/my_app < test_data_2.txt
+./target/release/my_app < typical_workload.txt
+
+# Step 3: Merge profile data
+llvm-profdata merge -o /tmp/pgo-data/merged.profdata /tmp/pgo-data
+
+# Step 4: Build optimized binary using profile
+RUSTFLAGS="-Cprofile-use=/tmp/pgo-data/merged.profdata" \
+    cargo build --release
+```
+
+## Cargo Configuration
+
+```toml
+# Cargo.toml
+[profile.release]
+lto = "fat"
+codegen-units = 1
+opt-level = 3
+
+# PGO flags set via RUSTFLAGS environment variable
+```
+
+## Build Script
+
+```bash
+#!/bin/bash
+set -e
+
+PGO_DIR=/tmp/pgo-$(date +%s)
+
+# Clean
+cargo clean
+
+# Instrumented build
+echo "Building instrumented binary..."
+RUSTFLAGS="-Cprofile-generate=$PGO_DIR" cargo build --release
+
+# Run workloads
+echo "Collecting profile data..."
+./target/release/my_app --benchmark-mode
+./target/release/my_app < test_fixtures/typical.txt
+./target/release/my_app < test_fixtures/stress.txt
+
+# Merge profiles
+echo "Merging profile data..."
+llvm-profdata merge -o $PGO_DIR/merged.profdata $PGO_DIR
+
+# Optimized build
+echo "Building optimized binary..."
+RUSTFLAGS="-Cprofile-use=$PGO_DIR/merged.profdata" cargo build --release
+
+echo "Done! Optimized binary at target/release/my_app"
+```
+
+## Representative Workloads
+
+```rust
+// Create benchmarks that match real usage patterns
+
+// Good: actual data samples
+fn profile_workload() {
+    for file in real_customer_data_samples() {
+        process_file(&file);
+    }
+}
+
+// Good: synthetic but realistic
+fn profile_synthetic() {
+    for _ in 0..10000 {
+        let data = generate_realistic_data();
+        process(&data);
+    }
+}
+
+// Bad: artificial microbenchmarks
+fn profile_bad() {
+    for _ in 0..1000000 {
+        small_operation();  // Doesn't reflect real hot paths
+    }
+}
+```
+
+## BOLT Post-Link Optimization
+
+For even more gains, combine PGO with BOLT:
+
+```bash
+# After PGO build, apply BOLT
+llvm-bolt target/release/my_app \
+    -o target/release/my_app.bolt \
+    -data=perf.data \
+    -reorder-blocks=ext-tsp \
+    -reorder-functions=hfsort
+
+# BOLT can add another 5-15% on top of PGO
+```
+
+## CI/CD Integration
+
+```yaml
+# GitHub Actions example
+jobs:
+  pgo-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Install LLVM tools
+        run: sudo apt-get install llvm
+      
+      - name: Instrumented build
+        run: RUSTFLAGS="-Cprofile-generate=/tmp/pgo" cargo build --release
+      
+      - name: Run profiling workloads
+        run: ./scripts/run_profiling_workloads.sh
+      
+      - name: Merge profiles
+        run: llvm-profdata merge -o /tmp/pgo/merged.profdata /tmp/pgo
+      
+      - name: Optimized build
+        run: RUSTFLAGS="-Cprofile-use=/tmp/pgo/merged.profdata" cargo build --release
+      
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: optimized-binary
+          path: target/release/my_app
+```
+
+## When to Use PGO
+
+| Use PGO | Skip PGO |
+|---------|----------|
+| Production deployments | Development builds |
+| Performance-critical apps | Libraries (users can PGO) |
+| Stable workload patterns | Highly variable workloads |
+| Sufficient profiling data | Quick iteration cycles |
+
+## See Also
+
+- [opt-lto-release](./opt-lto-release.md) - LTO works well with PGO
+- [opt-codegen-units](./opt-codegen-units.md) - Single codegen unit for PGO
+- [perf-profile-first](./perf-profile-first.md) - Profiling basics

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