agy-superpowers 5.2.2 → 5.2.3

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

@@ -1,125 +0,0 @@
-# anti-index-over-iter
-
-> Don't use indexing when iterators work
-
-## Why It Matters
-
-Manual indexing (`for i in 0..len`) requires bounds checks on every access, prevents SIMD optimization, and introduces off-by-one error risks. Iterators eliminate these issues and are more idiomatic Rust.
-
-## Bad
-
-```rust
-// Manual indexing - bounds checked every access
-fn sum_squares(data: &[i32]) -> i64 {
-    let mut result = 0i64;
-    for i in 0..data.len() {
-        result += (data[i] as i64) * (data[i] as i64);
-    }
-    result
-}
-
-// Index-based with multiple arrays
-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
-}
-
-// Mutation with indices
-fn normalize(data: &mut [f64]) {
-    let max = data.iter().cloned().fold(0.0, f64::max);
-    for i in 0..data.len() {
-        data[i] /= max;
-    }
-}
-```
-
-## Good
-
-```rust
-// Iterator - no bounds checks, SIMD-friendly
-fn sum_squares(data: &[i32]) -> i64 {
-    data.iter()
-        .map(|&x| (x as i64) * (x as i64))
-        .sum()
-}
-
-// Zip - handles length mismatch automatically
-fn dot_product(a: &[f64], b: &[f64]) -> f64 {
-    a.iter()
-        .zip(b.iter())
-        .map(|(&x, &y)| x * y)
-        .sum()
-}
-
-// Mutable iteration
-fn normalize(data: &mut [f64]) {
-    let max = data.iter().cloned().fold(0.0, f64::max);
-    for x in data.iter_mut() {
-        *x /= max;
-    }
-}
-```
-
-## When Indices Are Needed
-
-Sometimes you genuinely need indices:
-
-```rust
-// Need index in output
-for (i, item) in items.iter().enumerate() {
-    println!("{}: {}", i, item);
-}
-
-// Non-sequential access
-for i in (0..len).step_by(2) {
-    swap(&mut data[i], &mut data[i + 1]);
-}
-
-// Multi-dimensional iteration
-for i in 0..rows {
-    for j in 0..cols {
-        matrix[i][j] = i * cols + j;
-    }
-}
-```
-
-## Comparison
-
-| Pattern | Bounds Checks | SIMD | Safety |
-|---------|---------------|------|--------|
-| `for i in 0..len { data[i] }` | Every access | Limited | Off-by-one risk |
-| `for x in &data` | None | Good | Safe |
-| `for x in data.iter()` | None | Good | Safe |
-| `data.iter().enumerate()` | None | Good | Safe |
-
-## Common Conversions
-
-| Index Pattern | Iterator Pattern |
-|---------------|------------------|
-| `for i in 0..v.len()` | `for x in &v` |
-| `v[0]` | `v.first()` |
-| `v[v.len()-1]` | `v.last()` |
-| `for i in 0..a.len() { a[i] + b[i] }` | `a.iter().zip(&b)` |
-| `for i in 0..v.len() { v[i] *= 2 }` | `for x in &mut v { *x *= 2 }` |
-
-## Performance Note
-
-```rust
-// Iterator version can auto-vectorize
-let sum: i32 = data.iter().sum();
-
-// Manual indexing prevents vectorization
-let mut sum = 0;
-for i in 0..data.len() {
-    sum += data[i];
-}
-```
-
-## See Also
-
-- [perf-iter-over-index](./perf-iter-over-index.md) - Performance details
-- [opt-bounds-check](./opt-bounds-check.md) - Bounds check elimination
-- [perf-iter-lazy](./perf-iter-lazy.md) - Lazy iterators

package/template/agent/skills/rust-developer/references/rust-rules/anti-lock-across-await.md

@@ -1,127 +0,0 @@
-# anti-lock-across-await
-
-> Don't hold locks across await points
-
-## Why It Matters
-
-Holding a `Mutex` or `RwLock` guard across an `.await` causes the lock to be held while the task is suspended. Other tasks waiting for the lock block indefinitely. With `std::sync::Mutex`, this is even worse—it can deadlock the entire runtime.
-
-## Bad
-
-```rust
-use std::sync::Mutex;
-use tokio::sync::Mutex as AsyncMutex;
-
-// DEADLOCK RISK: std::sync::Mutex held across await
-async fn bad_std_mutex(data: &Mutex<Vec<i32>>) {
-    let mut guard = data.lock().unwrap();
-    do_async_work().await;  // Lock held during await!
-    guard.push(42);
-}
-
-// BLOCKS OTHER TASKS: tokio Mutex held across await
-async fn bad_async_mutex(data: &AsyncMutex<Vec<i32>>) {
-    let mut guard = data.lock().await;
-    slow_network_call().await;  // Lock held for entire call!
-    guard.push(42);
-}
-```
-
-## Good
-
-```rust
-use std::sync::Mutex;
-use tokio::sync::Mutex as AsyncMutex;
-
-// Release lock before await
-async fn good_approach(data: &Mutex<Vec<i32>>) {
-    let value = {
-        let guard = data.lock().unwrap();
-        guard.last().copied()  // Extract what you need
-    };  // Lock released here
-    
-    let result = do_async_work(value).await;
-    
-    {
-        let mut guard = data.lock().unwrap();
-        guard.push(result);
-    }
-}
-
-// Minimize lock scope with async mutex
-async fn good_async_mutex(data: &AsyncMutex<Vec<i32>>, item: i32) {
-    // Quick lock, quick release
-    data.lock().await.push(item);
-    
-    // Async work without lock
-    let result = slow_network_call().await;
-    
-    // Quick lock again
-    data.lock().await.push(result);
-}
-```
-
-## Pattern: Clone Before Await
-
-```rust
-async fn process(data: &AsyncMutex<Config>) -> Result<()> {
-    // Clone inside lock scope
-    let config = data.lock().await.clone();
-    
-    // Now use config freely across awaits
-    let result = fetch_data(&config.url).await?;
-    process_result(&config, result).await?;
-    
-    Ok(())
-}
-```
-
-## Pattern: Restructure to Avoid Lock
-
-```rust
-// Instead of locking a shared map
-struct Service {
-    data: AsyncMutex<HashMap<String, Data>>,
-}
-
-// Use channels or owned data
-struct BetterService {
-    // Each task owns its data via channels
-    sender: mpsc::Sender<Request>,
-}
-
-impl BetterService {
-    async fn request(&self, key: String) -> Data {
-        let (tx, rx) = oneshot::channel();
-        self.sender.send(Request { key, respond: tx }).await?;
-        rx.await?
-    }
-}
-```
-
-## What Can Cross Await
-
-| Type | Safe Across Await? |
-|------|--------------------|
-| `std::sync::Mutex` guard | **NO** - can deadlock |
-| `std::sync::RwLock` guard | **NO** - can deadlock |
-| `tokio::sync::Mutex` guard | Allowed but blocks tasks |
-| `tokio::sync::RwLock` guard | Allowed but blocks tasks |
-| Owned values | Yes |
-| `Arc<T>` | Yes |
-| References | Depends on lifetime |
-
-## Detection
-
-```toml
-# Cargo.toml
-[lints.clippy]
-await_holding_lock = "deny"
-await_holding_refcell_ref = "deny"
-```
-
-## See Also
-
-- [async-no-lock-await](./async-no-lock-await.md) - Async lock patterns
-- [async-clone-before-await](./async-clone-before-await.md) - Clone pattern
-- [own-mutex-interior](./own-mutex-interior.md) - Mutex usage

package/template/agent/skills/rust-developer/references/rust-rules/anti-over-abstraction.md

@@ -1,120 +0,0 @@
-# anti-over-abstraction
-
-> Don't over-abstract with excessive generics
-
-## Why It Matters
-
-Generics and traits are powerful but come at a cost: compile times, binary size, and cognitive load. Over-abstraction—making everything generic "for flexibility"—often adds complexity without benefit. Start concrete; generalize when you have real use cases.
-
-## Bad
-
-```rust
-// Overly generic for a simple function
-fn add<T, U, R>(a: T, b: U) -> R
-where
-    T: Into<R>,
-    U: Into<R>,
-    R: std::ops::Add<Output = R>,
-{
-    a.into() + b.into()
-}
-
-// Just call add(1, 2) - why make it this complex?
-
-// Trait explosion
-trait Readable {}
-trait Writable {}
-trait ReadWritable: Readable + Writable {}
-trait AsyncReadable {}
-trait AsyncWritable {}
-trait AsyncReadWritable: AsyncReadable + AsyncWritable {}
-
-// Abstract factory pattern (Java flashback)
-trait Factory<T> {
-    fn create(&self) -> T;
-}
-trait FactoryFactory<F: Factory<T>, T> {
-    fn create_factory(&self) -> F;
-}
-```
-
-## Good
-
-```rust
-// Concrete implementation - clear and simple
-fn add_i32(a: i32, b: i32) -> i32 {
-    a + b
-}
-
-// Generic when actually needed (e.g., library code)
-fn add<T: std::ops::Add<Output = T>>(a: T, b: T) -> T {
-    a + b
-}
-
-// Simple traits for actual polymorphism needs
-trait Storage {
-    fn save(&self, key: &str, value: &[u8]) -> Result<(), Error>;
-    fn load(&self, key: &str) -> Result<Vec<u8>, Error>;
-}
-
-// Concrete types first
-struct FileStorage { path: PathBuf }
-struct MemoryStorage { data: HashMap<String, Vec<u8>> }
-```
-
-## Signs of Over-Abstraction
-
-| Sign | Symptom |
-|------|---------|
-| Single implementation | Generic trait with only one impl |
-| Type parameter soup | `T, U, V, W` everywhere |
-| Marker traits | Traits with no methods |
-| Deep trait bounds | `where T: A + B + C + D + E` |
-| Phantom generics | Type parameters not used meaningfully |
-
-## When to Generalize
-
-Generalize when:
-- You have 2+ concrete types that share behavior
-- You're writing library code for public consumption
-- Performance requires static dispatch
-- The abstraction simplifies the API
-
-Don't generalize when:
-- You "might need it later" (YAGNI)
-- Only one type will ever implement it
-- It makes code harder to understand
-
-## Rule of Three
-
-Wait until you have three similar concrete implementations before abstracting:
-
-```rust
-// Version 1: Just FileStorage
-struct FileStorage { /* ... */ }
-
-// Version 2: Added MemoryStorage, similar interface
-struct MemoryStorage { /* ... */ }
-
-// Version 3: Now Redis too - time to abstract
-trait Storage {
-    fn save(&self, key: &str, value: &[u8]) -> Result<()>;
-    fn load(&self, key: &str) -> Result<Vec<u8>>;
-}
-```
-
-## Prefer Concrete Types in Private Code
-
-```rust
-// Internal function - concrete type is fine
-fn process_orders(db: &PostgresDb, orders: Vec<Order>) { }
-
-// Public API - might benefit from abstraction
-pub fn process_orders<S: Storage>(storage: &S, orders: Vec<Order>) { }
-```
-
-## See Also
-
-- [type-generic-bounds](./type-generic-bounds.md) - Minimal bounds
-- [api-sealed-trait](./api-sealed-trait.md) - Controlled extension
-- [anti-type-erasure](./anti-type-erasure.md) - When Box<dyn> is wrong

package/template/agent/skills/rust-developer/references/rust-rules/anti-panic-expected.md

@@ -1,131 +0,0 @@
-# anti-panic-expected
-
-> Don't panic on expected or recoverable errors
-
-## Why It Matters
-
-Panics crash the program. They're for unrecoverable situations—bugs, corrupted state, invariant violations. Using panic for expected conditions (network failures, file not found, invalid input) makes programs fragile and forces callers to catch panics or die.
-
-Use `Result` for recoverable errors.
-
-## Bad
-
-```rust
-// Network failures are expected
-fn fetch_data(url: &str) -> Data {
-    let response = reqwest::blocking::get(url)
-        .expect("network error");  // Crashes on timeout
-    response.json().expect("invalid json")  // Crashes on bad response
-}
-
-// User input is often invalid
-fn parse_config(input: &str) -> Config {
-    toml::from_str(input).expect("invalid config")  // Crashes on typo
-}
-
-// Files may not exist
-fn load_settings() -> Settings {
-    let content = fs::read_to_string("settings.json")
-        .expect("settings not found");  // Crashes if missing
-    serde_json::from_str(&content).expect("invalid settings")
-}
-
-// Custom panic for validation
-fn process_age(age: i32) {
-    if age < 0 {
-        panic!("age cannot be negative");  // Should return error
-    }
-}
-```
-
-## Good
-
-```rust
-// Return errors for expected failures
-fn fetch_data(url: &str) -> Result<Data, FetchError> {
-    let response = reqwest::blocking::get(url)
-        .context("failed to connect")?;
-    let data = response.json()
-        .context("failed to parse response")?;
-    Ok(data)
-}
-
-// Validate and return Result
-fn parse_config(input: &str) -> Result<Config, ConfigError> {
-    toml::from_str(input).map_err(ConfigError::Parse)
-}
-
-// Handle missing files gracefully
-fn load_settings() -> Result<Settings, SettingsError> {
-    let content = fs::read_to_string("settings.json")?;
-    let settings = serde_json::from_str(&content)?;
-    Ok(settings)
-}
-
-// Return error for validation failure
-fn process_age(age: i32) -> Result<(), ValidationError> {
-    if age < 0 {
-        return Err(ValidationError::NegativeAge);
-    }
-    Ok(())
-}
-```
-
-## When to Panic
-
-Panic IS appropriate for:
-
-```rust
-// Bug detection - invariant violated
-fn get_unchecked(&self, index: usize) -> &T {
-    assert!(index < self.len(), "index out of bounds - this is a bug");
-    unsafe { self.data.get_unchecked(index) }
-}
-
-// Unrecoverable state
-fn init() {
-    if !CAN_PROCEED {
-        panic!("system requirements not met");
-    }
-}
-
-// Tests
-#[test]
-fn test_fails() {
-    panic!("expected panic in test");
-}
-```
-
-## Decision Guide
-
-| Condition | Action |
-|-----------|--------|
-| Invalid user input | Return `Err` |
-| Network failure | Return `Err` |
-| File not found | Return `Err` |
-| Malformed data | Return `Err` |
-| Bug/impossible state | `panic!` or `unreachable!` |
-| Failed assertion in test | `panic!` |
-| Unrecoverable init failure | `panic!` |
-
-## Anti-pattern: panic! for Control Flow
-
-```rust
-// BAD: Using panic for control flow
-fn find_or_die(items: &[Item], id: u64) -> &Item {
-    items.iter()
-        .find(|i| i.id == id)
-        .unwrap_or_else(|| panic!("item {} not found", id))
-}
-
-// GOOD: Return Option or Result
-fn find(items: &[Item], id: u64) -> Option<&Item> {
-    items.iter().find(|i| i.id == id)
-}
-```
-
-## See Also
-
-- [err-result-over-panic](./err-result-over-panic.md) - Use Result
-- [anti-unwrap-abuse](./anti-unwrap-abuse.md) - Unwrap anti-pattern
-- [err-expect-bugs-only](./err-expect-bugs-only.md) - When to expect

package/template/agent/skills/rust-developer/references/rust-rules/anti-premature-optimize.md

@@ -1,156 +0,0 @@
-# anti-premature-optimize
-
-> Don't optimize before profiling
-
-## Why It Matters
-
-Premature optimization wastes time, complicates code, and often targets the wrong bottlenecks. Most code isn't performance-critical; the hot 10% matters. Profile first, then optimize the actual bottlenecks with data-driven decisions.
-
-## Bad
-
-```rust
-// "Optimizing" without measurement
-fn sum(data: &[i32]) -> i32 {
-    // Using unsafe "for performance" without profiling
-    unsafe {
-        let mut sum = 0;
-        for i in 0..data.len() {
-            sum += *data.get_unchecked(i);
-        }
-        sum
-    }
-}
-
-// Complex caching with no evidence it's needed
-lazy_static! {
-    static ref CACHE: RwLock<HashMap<String, Arc<Result>>> = 
-        RwLock::new(HashMap::new());
-}
-
-// Hand-rolled data structures "for speed"
-struct MyVec<T> {
-    ptr: *mut T,
-    len: usize,
-    cap: usize,
-}
-```
-
-## Good
-
-```rust
-// Simple, idiomatic - let compiler optimize
-fn sum(data: &[i32]) -> i32 {
-    data.iter().sum()
-}
-
-// Profile, then optimize if needed
-fn sum_optimized(data: &[i32]) -> i32 {
-    // After profiling showed this is a bottleneck,
-    // we measured that manual SIMD gives 3x speedup
-    #[cfg(target_arch = "x86_64")]
-    {
-        // SIMD implementation with benchmark data
-    }
-    #[cfg(not(target_arch = "x86_64"))]
-    {
-        data.iter().sum()
-    }
-}
-
-// Use standard library - it's well-optimized
-let cache: HashMap<String, Result> = HashMap::new();
-```
-
-## Profiling Workflow
-
-```bash
-# 1. Write correct code first
-cargo build --release
-
-# 2. Profile with real workloads
-cargo flamegraph --bin my_app -- --real-args
-# or
-cargo bench
-
-# 3. Identify hotspots (top 10% of time)
-
-# 4. Measure before optimizing
-# 5. Optimize ONE thing
-# 6. Measure after - verify improvement
-# 7. Repeat if still slow
-```
-
-## Optimization Principles
-
-| Do | Don't |
-|----|-------|
-| Profile first | Guess at bottlenecks |
-| Optimize hotspots | Optimize everything |
-| Measure improvement | Assume it's faster |
-| Keep it simple | Add complexity speculatively |
-| Trust the compiler | Outsmart the compiler |
-
-## When to Optimize
-
-```rust
-// AFTER profiling shows this is 40% of runtime
-#[inline]
-fn hot_function(data: &[u8]) -> u64 {
-    // Optimized implementation justified by benchmarks
-}
-
-// Clear, measurable benefit documented
-/// Pre-allocated buffer for repeated formatting.
-/// Benchmarks show 3x speedup for >1000 calls/sec workloads.
-struct FormatterPool {
-    buffers: Vec<String>,
-}
-```
-
-## Common Premature Optimizations
-
-| Premature | Reality |
-|-----------|---------|
-| `#[inline(always)]` everywhere | Compiler usually knows better |
-| `unsafe` for bounds check removal | Iterator does this safely |
-| Custom allocator | Default is usually fine |
-| Object pooling | Allocator is fast enough |
-| Manual SIMD | Auto-vectorization works |
-
-## Profile Tools
-
-```bash
-# Sampling profiler
-perf record ./target/release/app && perf report
-
-# Flamegraph
-cargo install flamegraph
-cargo flamegraph
-
-# Criterion benchmarks
-cargo bench
-
-# Memory profiling
-valgrind --tool=massif ./target/release/app
-```
-
-## Document Optimizations
-
-```rust
-/// Lookup table for fast character classification.
-/// 
-/// # Performance
-/// 
-/// Benchmarked with criterion (benchmarks/char_class.rs):
-/// - Table lookup: 2.3ns/op
-/// - Match statement: 8.7ns/op
-/// 
-/// Justified for hot path in parser (called 10M+ times).
-static CHAR_CLASS: [CharClass; 256] = [/* ... */];
-```
-
-## See Also
-
-- [perf-profile-first](./perf-profile-first.md) - Profile before optimize
-- [test-criterion-bench](./test-criterion-bench.md) - Benchmarking
-- [opt-inline-small](./opt-inline-small.md) - Inline guidelines