agy-superpowers 5.1.4 → 5.1.5

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

@@ -0,0 +1,131 @@
+# 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

@@ -0,0 +1,132 @@
+# 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

@@ -0,0 +1,95 @@
+# 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

@@ -0,0 +1,141 @@
+# 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

@@ -0,0 +1,125 @@
+# 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