agy-superpowers 5.2.1 → 5.2.3

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

package/template/agent/skills/rust-developer/references/rust-rules/proj-bin-dir.md

@@ -1,142 +0,0 @@
-# proj-bin-dir
-
-> Put multiple binaries in src/bin/
-
-## Why It Matters
-
-When a crate produces multiple binaries, placing them in `src/bin/` keeps the project organized. Each file becomes a separate binary target automatically, without manual `Cargo.toml` configuration.
-
-## Bad
-
-```
-my-project/
-├── Cargo.toml        # Complex [[bin]] sections for each binary
-├── src/
-│   ├── main.rs       # Which binary is this?
-│   ├── server.rs     # Is this a module or binary?
-│   ├── cli.rs        # Unclear
-│   └── lib.rs
-```
-
-```toml
-# Cargo.toml - verbose and error-prone
-[[bin]]
-name = "server"
-path = "src/server.rs"
-
-[[bin]]
-name = "cli"
-path = "src/cli.rs"
-```
-
-## Good
-
-```
-my-project/
-├── Cargo.toml        # Clean, no [[bin]] needed
-├── src/
-│   ├── lib.rs        # Shared library code
-│   └── bin/
-│       ├── server.rs # Binary: my-project-server (or just server)
-│       └── cli.rs    # Binary: my-project-cli (or just cli)
-```
-
-Each file in `src/bin/` automatically becomes a binary named after the file.
-
-## Running Binaries
-
-```bash
-# Run specific binary
-cargo run --bin server
-cargo run --bin cli
-
-# Build specific binary
-cargo build --bin server
-
-# Build all binaries
-cargo build --bins
-```
-
-## Pattern: Binary with Multiple Files
-
-For complex binaries, use directories:
-
-```
-src/
-├── lib.rs
-└── bin/
-    ├── server/
-    │   ├── main.rs      # Entry point
-    │   ├── config.rs    # Server-specific module
-    │   └── handlers.rs
-    └── cli/
-        ├── main.rs
-        └── commands.rs
-```
-
-## Pattern: Shared Library Code
-
-```rust
-// src/lib.rs - Shared code
-pub mod config;
-pub mod database;
-pub mod models;
-
-// src/bin/server.rs - Server binary
-use my_project::{config, database, models};
-
-fn main() {
-    let config = config::load();
-    let db = database::connect(&config);
-    // ...
-}
-
-// src/bin/cli.rs - CLI binary
-use my_project::{config, models};
-
-fn main() {
-    let config = config::load();
-    // CLI logic using shared code
-}
-```
-
-## Binary Naming
-
-| File Path | Binary Name |
-|-----------|-------------|
-| `src/main.rs` | `my-project` (crate name) |
-| `src/bin/server.rs` | `server` |
-| `src/bin/my-cli.rs` | `my-cli` |
-| `src/bin/server/main.rs` | `server` |
-
-## Explicit Configuration
-
-When you need custom settings:
-
-```toml
-[[bin]]
-name = "my-server"
-path = "src/bin/server.rs"
-required-features = ["server"]
-
-[[bin]]
-name = "my-cli"
-path = "src/bin/cli.rs"
-```
-
-## Pattern: Default Binary
-
-```toml
-# src/main.rs is the default binary
-# Additional binaries in src/bin/
-
-[package]
-name = "my-tool"
-default-run = "my-tool"  # Or specify another
-```
-
-## See Also
-
-- [proj-lib-main-split](./proj-lib-main-split.md) - Keep main.rs minimal
-- [proj-workspace-large](./proj-workspace-large.md) - Workspace for larger projects
-- [proj-flat-small](./proj-flat-small.md) - Simple project structure