agy-superpowers 5.2.2 → 5.2.3

package/template/agent/skills/rust-developer/references/rust-rules/perf-extend-batch.md

@@ -1,150 +0,0 @@
-# perf-extend-batch
-
-> Use extend for batch insertions
-
-## Why It Matters
-
-`extend()` can pre-allocate capacity for the incoming elements and insert them in a single operation. Individual `push()` calls may trigger multiple reallocations as the collection grows. For adding multiple elements, `extend()` is both faster and clearer.
-
-## Bad
-
-```rust
-// Multiple potential reallocations
-fn collect_results(sources: Vec<Source>) -> Vec<Result> {
-    let mut results = Vec::new();
-    
-    for source in sources {
-        for result in source.get_results() {
-            results.push(result);  // May reallocate
-        }
-    }
-    results
-}
-
-// Loop with push for known data
-fn build_list() -> Vec<i32> {
-    let mut list = Vec::new();
-    for i in 0..1000 {
-        list.push(i);  // Many reallocations
-    }
-    list
-}
-
-// Appending another collection
-fn combine(mut a: Vec<i32>, b: Vec<i32>) -> Vec<i32> {
-    for item in b {
-        a.push(item);
-    }
-    a
-}
-```
-
-## Good
-
-```rust
-// Single extend with size hint
-fn collect_results(sources: Vec<Source>) -> Vec<Result> {
-    let mut results = Vec::new();
-    
-    for source in sources {
-        results.extend(source.get_results());
-    }
-    results
-}
-
-// Direct collection from iterator
-fn build_list() -> Vec<i32> {
-    (0..1000).collect()
-}
-
-// Extend for combining
-fn combine(mut a: Vec<i32>, b: Vec<i32>) -> Vec<i32> {
-    a.extend(b);
-    a
-}
-```
-
-## Extend with Capacity
-
-For best performance, combine with `reserve()`:
-
-```rust
-fn merge_all(chunks: Vec<Vec<Item>>) -> Vec<Item> {
-    // Calculate total size
-    let total: usize = chunks.iter().map(|c| c.len()).sum();
-    
-    let mut result = Vec::with_capacity(total);
-    for chunk in chunks {
-        result.extend(chunk);
-    }
-    result
-}
-```
-
-## Extend Methods
-
-| Method | Description |
-|--------|-------------|
-| `.extend(iter)` | Add all elements from iterator |
-| `.extend_from_slice(&[T])` | Add from slice (for `Copy` types) |
-| `.append(&mut Vec)` | Move all from another Vec |
-
-## Pattern: Building Strings
-
-```rust
-// Bad: multiple allocations
-fn build_message(parts: &[&str]) -> String {
-    let mut result = String::new();
-    for part in parts {
-        result.push_str(part);  // May reallocate
-    }
-    result
-}
-
-// Good: extend with known parts
-fn build_message(parts: &[&str]) -> String {
-    let total_len: usize = parts.iter().map(|s| s.len()).sum();
-    let mut result = String::with_capacity(total_len);
-    for part in parts {
-        result.push_str(part);
-    }
-    result
-}
-
-// Better: collect/join
-fn build_message(parts: &[&str]) -> String {
-    parts.concat()  // or parts.join("")
-}
-```
-
-## HashMap/HashSet Extend
-
-```rust
-use std::collections::HashMap;
-
-// Extend from iterator of tuples
-fn merge_maps(mut base: HashMap<String, i32>, other: HashMap<String, i32>) -> HashMap<String, i32> {
-    base.extend(other);  // Moves entries from other
-    base
-}
-
-// Extend from iterator
-let mut set = HashSet::new();
-set.extend(items.iter().map(|i| i.id));
-```
-
-## Performance
-
-| Operation | Allocations | Complexity |
-|-----------|-------------|------------|
-| N × `push()` | O(log N) | O(N) amortized |
-| `extend(iter)` | O(1)* | O(N) |
-| `with_capacity` + `extend` | 1 | O(N) |
-
-*When iterator provides accurate `size_hint()`
-
-## See Also
-
-- [mem-with-capacity](./mem-with-capacity.md) - Pre-allocation
-- [perf-drain-reuse](./perf-drain-reuse.md) - Reusing allocations
-- [mem-reuse-collections](./mem-reuse-collections.md) - Collection reuse

package/template/agent/skills/rust-developer/references/rust-rules/perf-iter-lazy.md

@@ -1,123 +0,0 @@
-# perf-iter-lazy
-
-> Keep iterators lazy, collect only when needed
-
-## Why It Matters
-
-Rust iterators are lazy—they compute values on demand. This enables single-pass processing, avoids intermediate allocations, and allows short-circuiting. Calling `.collect()` too early forces evaluation and allocates unnecessarily.
-
-## Bad
-
-```rust
-// Collects intermediate results unnecessarily
-fn process(data: Vec<i32>) -> Vec<i32> {
-    let filtered: Vec<_> = data.into_iter()
-        .filter(|x| *x > 0)
-        .collect();  // Unnecessary allocation
-    
-    let mapped: Vec<_> = filtered.into_iter()
-        .map(|x| x * 2)
-        .collect();  // Another unnecessary allocation
-    
-    mapped.into_iter()
-        .take(10)
-        .collect()
-}
-
-// Collects before checking existence
-fn has_positive(data: &[i32]) -> bool {
-    let positives: Vec<_> = data.iter()
-        .filter(|&&x| x > 0)
-        .collect();  // Allocates entire filtered result
-    
-    !positives.is_empty()
-}
-```
-
-## Good
-
-```rust
-// Single chain, single collect
-fn process(data: Vec<i32>) -> Vec<i32> {
-    data.into_iter()
-        .filter(|x| *x > 0)
-        .map(|x| x * 2)
-        .take(10)
-        .collect()
-}
-
-// Short-circuits on first match
-fn has_positive(data: &[i32]) -> bool {
-    data.iter().any(|&x| x > 0)
-}
-```
-
-## Lazy Iterator Methods
-
-These methods return iterators (lazy):
-
-| Method | Description |
-|--------|-------------|
-| `.filter()` | Keep matching elements |
-| `.map()` | Transform elements |
-| `.take(n)` | Limit to n elements |
-| `.skip(n)` | Skip first n elements |
-| `.zip()` | Pair with another iterator |
-| `.chain()` | Concatenate iterators |
-| `.flat_map()` | Map and flatten |
-| `.enumerate()` | Add index |
-
-## Consuming Methods
-
-These methods consume the iterator (evaluate immediately):
-
-| Method | Description |
-|--------|-------------|
-| `.collect()` | Gather into collection |
-| `.for_each()` | Execute side effect |
-| `.count()` | Count elements |
-| `.sum()` | Sum elements |
-| `.fold()` | Accumulate value |
-| `.any()` | Check if any match |
-| `.all()` | Check if all match |
-| `.find()` | Find first match |
-
-## Short-Circuit Benefits
-
-```rust
-// Without lazy: processes ALL items
-let found: Vec<_> = items.iter()
-    .filter(|x| expensive_check(x))
-    .collect();
-let result = found.first();
-
-// With lazy: stops at first match
-let result = items.iter()
-    .find(|x| expensive_check(x));
-```
-
-## Pattern: Process Without Collecting
-
-```rust
-// Print all matches without allocating
-data.iter()
-    .filter(|x| x.is_valid())
-    .for_each(|x| println!("{}", x));
-
-// Count without collecting
-let count = data.iter()
-    .filter(|x| x.is_valid())
-    .count();
-
-// Sum without intermediate collection
-let total: i64 = data.iter()
-    .filter(|x| x.is_valid())
-    .map(|x| x.value as i64)
-    .sum();
-```
-
-## See Also
-
-- [perf-collect-once](./perf-collect-once.md) - Single collect
-- [perf-iter-over-index](./perf-iter-over-index.md) - Prefer iterators
-- [anti-collect-intermediate](./anti-collect-intermediate.md) - Anti-pattern

package/template/agent/skills/rust-developer/references/rust-rules/perf-iter-over-index.md

@@ -1,113 +0,0 @@
-# perf-iter-over-index
-
-> Prefer iterators over manual indexing
-
-## Why It Matters
-
-Iterators are the idiomatic way to traverse collections in Rust. They enable bounds check elimination, SIMD auto-vectorization, and cleaner code. Manual indexing (`for i in 0..len`) often prevents these optimizations and introduces off-by-one error risks.
-
-## Bad
-
-```rust
-// Manual indexing - bounds checked every iteration
-fn sum_squares(data: &[i32]) -> i64 {
-    let mut sum = 0i64;
-    for i in 0..data.len() {
-        sum += (data[i] as i64) * (data[i] as i64);
-    }
-    sum
-}
-
-// Index-based iteration with multiple collections
-fn dot_product(a: &[f64], b: &[f64]) -> f64 {
-    let mut sum = 0.0;
-    for i in 0..a.len().min(b.len()) {
-        sum += a[i] * b[i];
-    }
-    sum
-}
-
-// Mutating with indices
-fn double_values(data: &mut [i32]) {
-    for i in 0..data.len() {
-        data[i] *= 2;
-    }
-}
-```
-
-## Good
-
-```rust
-// Iterator - bounds checks eliminated, SIMD-friendly
-fn sum_squares(data: &[i32]) -> i64 {
-    data.iter()
-        .map(|&x| (x as i64) * (x as i64))
-        .sum()
-}
-
-// Zip iterators - no manual length handling
-fn dot_product(a: &[f64], b: &[f64]) -> f64 {
-    a.iter()
-        .zip(b.iter())
-        .map(|(&x, &y)| x * y)
-        .sum()
-}
-
-// Mutable iteration
-fn double_values(data: &mut [i32]) {
-    for x in data.iter_mut() {
-        *x *= 2;
-    }
-}
-```
-
-## When Indexing Is Needed
-
-Sometimes you genuinely need indices:
-
-```rust
-// Need the index for output or processing
-for (i, value) in data.iter().enumerate() {
-    println!("Index {}: {}", i, value);
-}
-
-// Non-sequential access patterns
-fn interleave(data: &mut [i32]) {
-    let mid = data.len() / 2;
-    for i in 0..mid {
-        data.swap(i * 2, mid + i);
-    }
-}
-```
-
-## Performance Comparison
-
-| Pattern | Bounds Checks | SIMD Potential | Clarity |
-|---------|---------------|----------------|---------|
-| `for i in 0..len` | Every access | Limited | Medium |
-| `for &x in slice` | None | High | High |
-| `.iter().enumerate()` | None | Medium | High |
-| `get_unchecked` | None (unsafe) | High | Low |
-
-## Iterator Advantages
-
-```rust
-// Chaining operations - single pass
-let result: Vec<_> = data.iter()
-    .filter(|x| **x > 0)
-    .map(|x| x * 2)
-    .collect();
-
-// Early termination optimized
-let found = data.iter().any(|&x| x == target);
-
-// Parallel iteration (with rayon)
-use rayon::prelude::*;
-let sum: i64 = data.par_iter().map(|&x| x as i64).sum();
-```
-
-## See Also
-
-- [perf-iter-lazy](./perf-iter-lazy.md) - Keep iterators lazy
-- [opt-bounds-check](./opt-bounds-check.md) - Bounds check elimination
-- [anti-index-over-iter](./anti-index-over-iter.md) - Anti-pattern

package/template/agent/skills/rust-developer/references/rust-rules/perf-profile-first.md

@@ -1,175 +0,0 @@
-# perf-profile-first
-
-> Profile before optimizing
-
-## Why It Matters
-
-Intuition about performance is often wrong. The code you think is slow frequently isn't, while actual bottlenecks hide in unexpected places. Profiling shows you exactly where time is spent, preventing wasted effort on optimizations that don't matter.
-
-## Bad
-
-```rust
-// Optimizing without measuring
-fn process(data: &[Item]) -> Vec<Output> {
-    // "I bet this clone is slow..."
-    let cloned: Vec<_> = data.iter().cloned().collect();
-    
-    // Actually, 99% of time is spent here:
-    cloned.iter().map(|x| expensive_computation(x)).collect()
-}
-
-// Over-engineering rarely-called code
-#[inline(always)]
-fn rarely_called() {
-    // This runs once at startup...
-}
-```
-
-## Good
-
-```rust
-// 1. Profile first
-// cargo flamegraph --bin myapp
-// cargo instruments -t time --bin myapp (macOS)
-
-// 2. Find the actual bottleneck
-// Flamegraph shows expensive_computation takes 95% of time
-
-// 3. Optimize the hot spot
-fn process(data: &[Item]) -> Vec<Output> {
-    // Clone is fine - only 1% of time
-    let cloned: Vec<_> = data.iter().cloned().collect();
-    
-    // Focus optimization HERE
-    cloned.par_iter()  // Parallelize the expensive part
-        .map(|x| expensive_computation(x))
-        .collect()
-}
-```
-
-## Profiling Tools
-
-### Flamegraphs (Recommended Start)
-
-```bash
-# Install
-cargo install flamegraph
-
-# Profile
-cargo flamegraph --bin myapp -- <args>
-
-# Opens flamegraph.svg showing call stacks by time
-```
-
-### perf (Linux)
-
-```bash
-# Record
-perf record -g cargo run --release
-
-# Report
-perf report
-
-# Or generate flamegraph
-perf script | inferno-collapse-perf | inferno-flamegraph > flamegraph.svg
-```
-
-### Instruments (macOS)
-
-```bash
-# Install cargo-instruments
-cargo install cargo-instruments
-
-# Time profiler
-cargo instruments -t time --release
-
-# Allocations profiler
-cargo instruments -t alloc --release
-```
-
-### DHAT (Heap Profiling)
-
-```bash
-# In your code
-#[global_allocator]
-static ALLOC: dhat::Alloc = dhat::Alloc;
-
-fn main() {
-    let _profiler = dhat::Profiler::new_heap();
-    // ... your code
-}
-
-# Run and get allocation report
-cargo run --release
-```
-
-### criterion (Micro-benchmarks)
-
-```rust
-use criterion::{black_box, criterion_group, criterion_main, Criterion};
-
-fn bench_my_function(c: &mut Criterion) {
-    c.bench_function("my_function", |b| {
-        b.iter(|| my_function(black_box(input)))
-    });
-}
-
-criterion_group!(benches, bench_my_function);
-criterion_main!(benches);
-```
-
-## What to Look For
-
-```
-Flamegraph Reading:
-├── Width = time spent
-├── Height = call stack depth
-└── Look for:
-    ├── Wide bars (time hogs)
-    ├── malloc/free (allocation heavy)
-    ├── memcpy (copying data)
-    └── Unexpected functions taking time
-```
-
-## Common Findings
-
-```rust
-// Finding: HashMap operations are slow
-// Fix: Use FxHashMap or AHashMap for non-crypto hashing
-
-// Finding: String allocation in hot loop
-// Fix: Pre-allocate with capacity, use &str
-
-// Finding: Clone in hot path
-// Fix: Use references or Cow
-
-// Finding: Bounds checks visible in profile
-// Fix: Use iterators instead of indexing
-
-// Finding: Lock contention
-// Fix: Reduce critical section, use RwLock, or partition data
-```
-
-## Optimization Workflow
-
-```
-1. Write correct code first
-2. Write benchmarks for hot paths
-3. Profile under realistic load
-4. Identify actual bottlenecks
-5. Optimize ONE thing
-6. Measure improvement
-7. Repeat if needed
-```
-
-## Evidence: Rust Performance Book
-
-> "The biggest performance improvements often come from changes to algorithms or data structures, rather than low-level optimizations."
-
-> "It is worth understanding which Rust data structures and operations cause allocations, because avoiding them can greatly improve performance."
-
-## See Also
-
-- [opt-lto-release](opt-lto-release.md) - Enable LTO for release builds
-- [test-criterion-bench](test-criterion-bench.md) - Use criterion for benchmarking
-- [anti-premature-optimize](anti-premature-optimize.md) - Don't optimize without data

package/template/agent/skills/rust-developer/references/rust-rules/perf-release-profile.md

@@ -1,149 +0,0 @@
-# perf-release-profile
-
-> Optimize release profile settings
-
-## Why It Matters
-
-The default release profile prioritizes compile speed over runtime performance. For production binaries, tuning the release profile can yield significant performance improvements (10-40% in some cases) at the cost of longer compile times.
-
-## Default Profile
-
-```toml
-[profile.release]
-opt-level = 3
-debug = false
-lto = false
-codegen-units = 16
-```
-
-## Optimized Profile
-
-```toml
-[profile.release]
-opt-level = 3          # Maximum optimization
-lto = "fat"            # Full link-time optimization
-codegen-units = 1      # Better optimization, slower compile
-panic = "abort"        # Smaller binary, no unwinding
-strip = true           # Remove symbols
-
-[profile.release.package."*"]
-# Keep dependencies optimized even if main crate changes
-opt-level = 3
-```
-
-## Profile Options
-
-| Option | Values | Effect |
-|--------|--------|--------|
-| `opt-level` | 0-3, "s", "z" | Optimization level |
-| `lto` | false, "thin", "fat" | Link-time optimization |
-| `codegen-units` | 1-256 | Parallel compilation units |
-| `panic` | "unwind", "abort" | Panic behavior |
-| `strip` | true, false, "symbols", "debuginfo" | Binary stripping |
-| `debug` | true, false, 0-2 | Debug info level |
-
-## Optimization Levels
-
-| Level | Description | Use Case |
-|-------|-------------|----------|
-| `0` | No optimization | Debug builds |
-| `1` | Basic optimization | Fast compile |
-| `2` | Most optimizations | Balanced |
-| `3` | All optimizations | Maximum performance |
-| `"s"` | Optimize for size | Embedded |
-| `"z"` | Minimize size | Smallest binary |
-
-## LTO Options
-
-| Option | Compile Time | Performance | Binary Size |
-|--------|--------------|-------------|-------------|
-| `false` | Fast | Baseline | Larger |
-| `"thin"` | Medium | Good | Smaller |
-| `"fat"` | Slow | Best | Smallest |
-
-## Custom Profiles
-
-```toml
-# Fast release builds for development
-[profile.release-dev]
-inherits = "release"
-lto = false
-codegen-units = 16
-
-# Maximum performance for production
-[profile.release-prod]
-inherits = "release"
-lto = "fat"
-codegen-units = 1
-strip = true
-
-# Profiling with symbols
-[profile.profiling]
-inherits = "release"
-debug = true
-strip = false
-```
-
-Use with: `cargo build --profile release-prod`
-
-## Dev Dependencies Optimization
-
-Speed up tests and dev builds:
-
-```toml
-[profile.dev]
-opt-level = 0
-
-# Optimize dependencies even in dev
-[profile.dev.package."*"]
-opt-level = 3
-```
-
-## Benchmarking Profile
-
-```toml
-[profile.bench]
-inherits = "release"
-debug = true      # For profiling
-strip = false     # Keep symbols for flamegraphs
-lto = "fat"       # Consistent with release-prod
-```
-
-## Size vs Speed Trade-offs
-
-```toml
-# Smallest binary
-[profile.min-size]
-inherits = "release"
-opt-level = "z"
-lto = "fat"
-codegen-units = 1
-panic = "abort"
-strip = true
-
-# Balance size and speed
-[profile.balanced]
-inherits = "release"
-opt-level = "s"
-lto = "thin"
-```
-
-## Workspace Configuration
-
-```toml
-# In workspace Cargo.toml
-[profile.release]
-lto = "fat"
-codegen-units = 1
-
-# Override for specific package
-[profile.release.package.fast-compile-lib]
-lto = false
-codegen-units = 16
-```
-
-## See Also
-
-- [opt-lto-release](./opt-lto-release.md) - LTO details
-- [opt-codegen-units](./opt-codegen-units.md) - Codegen units
-- [opt-pgo-profile](./opt-pgo-profile.md) - Profile-guided optimization