agy-superpowers 5.2.2 → 5.2.4

package/template/agent/skills/rust-developer/references/rust-rules/anti-collect-intermediate.md

@@ -1,131 +0,0 @@
-# anti-collect-intermediate
-
-> Don't collect intermediate iterators
-
-## Why It Matters
-
-Each `.collect()` allocates a new collection. Collecting intermediate results in a chain creates unnecessary allocations and prevents iterator fusion. Keep the chain lazy; collect only at the end.
-
-## Bad
-
-```rust
-// Three allocations, three passes
-fn process(data: Vec<i32>) -> Vec<i32> {
-    let step1: Vec<_> = data.into_iter()
-        .filter(|x| *x > 0)
-        .collect();
-    
-    let step2: Vec<_> = step1.into_iter()
-        .map(|x| x * 2)
-        .collect();
-    
-    step2.into_iter()
-        .filter(|x| *x < 100)
-        .collect()
-}
-
-// Collecting just to check length
-fn has_valid_items(items: &[Item]) -> bool {
-    let valid: Vec<_> = items.iter()
-        .filter(|i| i.is_valid())
-        .collect();
-    !valid.is_empty()
-}
-
-// Collecting to iterate again
-fn sum_valid(items: &[Item]) -> i64 {
-    let valid: Vec<_> = items.iter()
-        .filter(|i| i.is_valid())
-        .collect();
-    valid.iter().map(|i| i.value).sum()
-}
-```
-
-## Good
-
-```rust
-// Single allocation, single pass
-fn process(data: Vec<i32>) -> Vec<i32> {
-    data.into_iter()
-        .filter(|x| *x > 0)
-        .map(|x| x * 2)
-        .filter(|x| *x < 100)
-        .collect()
-}
-
-// No allocation - iterator short-circuits
-fn has_valid_items(items: &[Item]) -> bool {
-    items.iter().any(|i| i.is_valid())
-}
-
-// No intermediate allocation
-fn sum_valid(items: &[Item]) -> i64 {
-    items.iter()
-        .filter(|i| i.is_valid())
-        .map(|i| i.value)
-        .sum()
-}
-```
-
-## When Collection Is Needed
-
-```rust
-// Need to iterate twice
-let valid: Vec<_> = items.iter()
-    .filter(|i| i.is_valid())
-    .collect();
-let count = valid.len();
-for item in &valid {
-    process(item);
-}
-
-// Need to sort (requires concrete collection)
-let mut sorted: Vec<_> = items.iter()
-    .filter(|i| i.is_active())
-    .collect();
-sorted.sort_by_key(|i| i.priority);
-
-// Need random access
-let indexed: Vec<_> = items.iter().collect();
-let middle = indexed.get(indexed.len() / 2);
-```
-
-## Iterator Methods That Avoid Collection
-
-| Instead of Collecting to... | Use |
-|-----------------------------|-----|
-| Check if empty | `.any(|_| true)` or `.next().is_some()` |
-| Check if any match | `.any(predicate)` |
-| Check if all match | `.all(predicate)` |
-| Count elements | `.count()` |
-| Sum elements | `.sum()` |
-| Find first | `.find(predicate)` |
-| Get first | `.next()` |
-| Get last | `.last()` |
-
-## Pattern: Deferred Collection
-
-```rust
-// Return iterator, let caller collect if needed
-fn valid_items(items: &[Item]) -> impl Iterator<Item = &Item> {
-    items.iter().filter(|i| i.is_valid())
-}
-
-// Caller decides
-let count = valid_items(&items).count();  // No collection
-let vec: Vec<_> = valid_items(&items).collect();  // Collection when needed
-```
-
-## Comparison
-
-| Pattern | Allocations | Passes |
-|---------|-------------|--------|
-| `.collect()` each step | N | N |
-| Single chain, one `.collect()` | 1 | 1 |
-| No collection (streaming) | 0 | 1 |
-
-## See Also
-
-- [perf-collect-once](./perf-collect-once.md) - Single collect
-- [perf-iter-lazy](./perf-iter-lazy.md) - Lazy evaluation
-- [perf-iter-over-index](./perf-iter-over-index.md) - Iterator patterns

package/template/agent/skills/rust-developer/references/rust-rules/anti-empty-catch.md

@@ -1,132 +0,0 @@
-# anti-empty-catch
-
-> Don't silently ignore errors
-
-## Why It Matters
-
-Empty error handling (`if let Err(_) = ...`, `let _ = result`, `.ok()`) silently discards errors. Failures go unnoticed, bugs hide, and debugging becomes impossible. Every error deserves acknowledgment—even if just logging.
-
-## Bad
-
-```rust
-// Silently ignores errors
-let _ = write_to_file(data);
-
-// Discards error completely
-if let Err(_) = send_notification() {
-    // Nothing - error vanishes
-}
-
-// Converts Result to Option, losing error info
-let value = risky_operation().ok();
-
-// Match with empty arm
-match database.save(record) {
-    Ok(_) => println!("saved"),
-    Err(_) => {}  // Silent failure
-}
-
-// Ignored in loop
-for item in items {
-    let _ = process(item);  // Failures unnoticed
-}
-```
-
-## Good
-
-```rust
-// Log the error
-if let Err(e) = write_to_file(data) {
-    error!("failed to write file: {}", e);
-}
-
-// Propagate if possible
-send_notification()?;
-
-// Or handle explicitly
-match send_notification() {
-    Ok(_) => info!("notification sent"),
-    Err(e) => warn!("notification failed: {}", e),
-}
-
-// Collect errors in batch operations
-let (successes, failures): (Vec<_>, Vec<_>) = items
-    .into_iter()
-    .map(process)
-    .partition(Result::is_ok);
-
-if !failures.is_empty() {
-    warn!("{} items failed to process", failures.len());
-}
-
-// Explicit documentation when ignoring
-// Intentionally ignored: cleanup failure is not critical
-let _ = cleanup_temp_file();  // Add comment explaining why
-```
-
-## Acceptable Ignoring (Documented)
-
-```rust
-// Close errors often ignored, but document it
-// INTENTIONAL: TCP close errors are not actionable
-let _ = stream.shutdown(Shutdown::Both);
-
-// Mutex poisoning recovery
-// INTENTIONAL: We'll reset the state anyway
-let guard = mutex.lock().unwrap_or_else(|e| e.into_inner());
-```
-
-## Pattern: Collect and Report
-
-```rust
-fn process_batch(items: Vec<Item>) -> BatchResult {
-    let mut errors = Vec::new();
-    
-    for item in items {
-        if let Err(e) = process_item(&item) {
-            errors.push((item.id, e));
-        }
-    }
-    
-    if errors.is_empty() {
-        BatchResult::AllSucceeded
-    } else {
-        BatchResult::PartialFailure(errors)
-    }
-}
-```
-
-## Pattern: Best-Effort Operations
-
-```rust
-// Metrics/telemetry can fail without affecting main flow
-fn report_metric(name: &str, value: f64) {
-    if let Err(e) = metrics_client.record(name, value) {
-        // Log but don't propagate - metrics are not critical
-        debug!("failed to record metric {}: {}", name, e);
-    }
-}
-```
-
-## Clippy Lint
-
-```toml
-[lints.clippy]
-let_underscore_drop = "warn"
-ignored_unit_patterns = "warn"
-```
-
-## Decision Guide
-
-| Situation | Action |
-|-----------|--------|
-| Critical operation | `?` or handle explicitly |
-| Non-critical, debugging needed | Log the error |
-| Truly ignorable (rare) | `let _ =` with comment |
-| Batch operation | Collect errors, report |
-
-## See Also
-
-- [err-result-over-panic](./err-result-over-panic.md) - Proper error handling
-- [err-context-chain](./err-context-chain.md) - Adding context
-- [anti-unwrap-abuse](./anti-unwrap-abuse.md) - Unwrap issues

package/template/agent/skills/rust-developer/references/rust-rules/anti-expect-lazy.md

@@ -1,95 +0,0 @@
-# anti-expect-lazy
-
-> Don't use expect for recoverable errors
-
-## Why It Matters
-
-`.expect()` panics with a custom message, but it's still a panic. Using it for errors that could reasonably occur in production (network failures, file not found, invalid input) crashes the program instead of handling the error gracefully.
-
-Reserve `.expect()` for programming errors where panic is appropriate.
-
-## Bad
-
-```rust
-// Network failures are expected - don't panic
-let response = client.get(url).await.expect("failed to fetch");
-
-// Files might not exist
-let config = fs::read_to_string("config.toml").expect("config not found");
-
-// User input can be invalid
-let age: u32 = input.parse().expect("invalid age");
-
-// Database queries can fail
-let user = db.find_user(id).await.expect("user not found");
-```
-
-## Good
-
-```rust
-// Handle recoverable errors properly
-let response = client.get(url).await
-    .context("failed to fetch URL")?;
-
-// Return error if file doesn't exist
-let config = fs::read_to_string("config.toml")
-    .context("failed to read config file")?;
-
-// Validate and return error
-let age: u32 = input.parse()
-    .map_err(|_| Error::InvalidInput("age must be a number"))?;
-
-// Handle missing data
-let user = db.find_user(id).await?
-    .ok_or(Error::NotFound("user"))?;
-```
-
-## When expect() Is Appropriate
-
-Use `.expect()` for invariants that indicate bugs:
-
-```rust
-// Mutex poisoning indicates a bug elsewhere
-let guard = mutex.lock().expect("mutex poisoned");
-
-// Regex is known valid at compile time
-let re = Regex::new(r"^\d{4}$").expect("invalid regex");
-
-// Thread spawn failure is unrecoverable
-let handle = thread::spawn(|| work()).expect("failed to spawn thread");
-
-// Static data that must be valid
-let config: Config = toml::from_str(EMBEDDED_CONFIG)
-    .expect("embedded config is invalid");
-```
-
-## Pattern: expect() vs unwrap()
-
-```rust
-// unwrap: no context, hard to debug
-let x = option.unwrap();
-
-// expect: gives context, still panics
-let x = option.expect("value should exist after validation");
-
-// ?: proper error handling
-let x = option.ok_or(Error::MissingValue)?;
-```
-
-## Decision Guide
-
-| Situation | Use |
-|-----------|-----|
-| User input | `?` with error |
-| File/network I/O | `?` with error |
-| Database operations | `?` with error |
-| Parsed constants | `.expect()` |
-| Thread/mutex operations | `.expect()` |
-| After validation check | `.expect()` with explanation |
-| Never expected to fail | `.expect()` documenting invariant |
-
-## See Also
-
-- [err-expect-bugs-only](./err-expect-bugs-only.md) - When to use expect
-- [err-no-unwrap-prod](./err-no-unwrap-prod.md) - Avoiding unwrap
-- [anti-unwrap-abuse](./anti-unwrap-abuse.md) - Unwrap anti-pattern

package/template/agent/skills/rust-developer/references/rust-rules/anti-format-hot-path.md

@@ -1,141 +0,0 @@
-# anti-format-hot-path
-
-> Don't use format! in hot paths
-
-## Why It Matters
-
-`format!()` allocates a new `String` every call. In hot paths (loops, frequently called functions), this creates allocation churn that impacts performance. Pre-allocate, reuse buffers, or use `write!()` to an existing buffer.
-
-## Bad
-
-```rust
-// format! in loop - allocates every iteration
-fn log_events(events: &[Event]) {
-    for event in events {
-        let message = format!("[{}] {}: {}", event.level, event.source, event.message);
-        logger.log(&message);
-    }
-}
-
-// format! for building parts
-fn build_url(base: &str, path: &str, params: &[(&str, &str)]) -> String {
-    let mut url = format!("{}{}", base, path);
-    for (key, value) in params {
-        url = format!("{}{}={}&", url, key, value);  // New allocation each time
-    }
-    url
-}
-
-// format! for simple concatenation
-fn greet(name: &str) -> String {
-    format!("Hello, {}!", name)  // Fine for one-off, bad if called 1M times
-}
-```
-
-## Good
-
-```rust
-use std::fmt::Write;
-
-// Reuse buffer across iterations
-fn log_events(events: &[Event]) {
-    let mut buffer = String::with_capacity(256);
-    for event in events {
-        buffer.clear();
-        write!(buffer, "[{}] {}: {}", event.level, event.source, event.message).unwrap();
-        logger.log(&buffer);
-    }
-}
-
-// Build incrementally in single buffer
-fn build_url(base: &str, path: &str, params: &[(&str, &str)]) -> String {
-    let mut url = String::with_capacity(base.len() + path.len() + params.len() * 20);
-    url.push_str(base);
-    url.push_str(path);
-    for (key, value) in params {
-        write!(url, "{}={}&", key, value).unwrap();
-    }
-    url
-}
-
-// For truly hot paths, avoid allocation entirely
-fn greet_to_buf(name: &str, buffer: &mut String) {
-    buffer.clear();
-    buffer.push_str("Hello, ");
-    buffer.push_str(name);
-    buffer.push('!');
-}
-```
-
-## Comparison
-
-| Approach | Allocations | Performance |
-|----------|-------------|-------------|
-| `format!()` in loop | N | Slow |
-| `write!()` to reused buffer | 1 | Fast |
-| `push_str()` + `push()` | 1 | Fastest |
-| Pre-sized `String::with_capacity()` | 1 (no realloc) | Fast |
-
-## When format! Is Fine
-
-```rust
-// One-time initialization
-let config_path = format!("{}/config.toml", home_dir);
-
-// Error messages (not hot path)
-return Err(format!("invalid input: {}", input));
-
-// Debug output
-println!("Debug: {:?}", value);
-```
-
-## Pattern: Formatter Buffer Pool
-
-```rust
-use std::cell::RefCell;
-
-thread_local! {
-    static BUFFER: RefCell<String> = RefCell::new(String::with_capacity(256));
-}
-
-fn format_event(event: &Event) -> String {
-    BUFFER.with(|buf| {
-        let mut buf = buf.borrow_mut();
-        buf.clear();
-        write!(buf, "[{}] {}", event.level, event.message).unwrap();
-        buf.clone()  // Still one allocation per call, but no parsing
-    })
-}
-```
-
-## Pattern: Display Implementation
-
-```rust
-struct Event {
-    level: Level,
-    message: String,
-}
-
-impl std::fmt::Display for Event {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(f, "[{}] {}", self.level, self.message)
-    }
-}
-
-// Caller controls allocation
-let mut buf = String::new();
-write!(buf, "{}", event)?;
-```
-
-## Clippy Lint
-
-```toml
-[lints.clippy]
-format_in_format_args = "warn"
-```
-
-## See Also
-
-- [mem-avoid-format](./mem-avoid-format.md) - Avoiding format
-- [mem-write-over-format](./mem-write-over-format.md) - Using write!
-- [mem-reuse-collections](./mem-reuse-collections.md) - Buffer reuse

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