agy-superpowers 5.2.2 → 5.2.3

package/template/agent/skills/rust-developer/references/rust-rules/anti-clone-excessive.md

@@ -1,124 +0,0 @@
-# anti-clone-excessive
-
-> Don't clone when borrowing works
-
-## Why It Matters
-
-`.clone()` allocates memory and copies data. When you only need to read data, borrowing (`&T`) is free. Excessive cloning wastes memory, CPU cycles, and often indicates misunderstanding of ownership.
-
-## Bad
-
-```rust
-// Cloning to pass to a function that only reads
-fn print_name(name: String) {  // Takes ownership
-    println!("{}", name);
-}
-let name = "Alice".to_string();
-print_name(name.clone());  // Unnecessary clone
-print_name(name);          // Could have just done this
-
-// Cloning in a loop
-for item in items.clone() {  // Clones entire Vec
-    process(&item);
-}
-
-// Cloning for comparison
-if input.clone() == expected {  // Pointless clone
-    // ...
-}
-
-// Cloning struct fields
-fn get_name(&self) -> String {
-    self.name.clone()  // Caller might not need ownership
-}
-```
-
-## Good
-
-```rust
-// Accept reference if only reading
-fn print_name(name: &str) {
-    println!("{}", name);
-}
-let name = "Alice".to_string();
-print_name(&name);  // Borrow, no clone
-
-// Iterate by reference
-for item in &items {
-    process(item);
-}
-
-// Compare by reference
-if input == expected {
-    // ...
-}
-
-// Return reference when possible
-fn get_name(&self) -> &str {
-    &self.name
-}
-```
-
-## When to Clone
-
-```rust
-// Need owned data for async move
-let name = name.clone();
-tokio::spawn(async move {
-    process(name).await;
-});
-
-// Storing in a new struct
-struct Cache {
-    data: String,
-}
-impl Cache {
-    fn store(&mut self, data: &str) {
-        self.data = data.to_string();  // Must own
-    }
-}
-
-// Multiple owners (use Arc instead if frequent)
-let shared = data.clone();
-thread::spawn(move || use_data(shared));
-```
-
-## Alternatives to Clone
-
-| Instead of | Use |
-|------------|-----|
-| `s.clone()` for reading | `&s` |
-| `vec.clone()` for iteration | `&vec` or `vec.iter()` |
-| `Clone` for shared ownership | `Arc<T>` |
-| Clone in hot loop | Move outside loop |
-| `s.to_string()` from `&str` | Accept `&str` if possible |
-
-## Pattern: Clone on Write
-
-```rust
-use std::borrow::Cow;
-
-fn process(input: Cow<str>) -> Cow<str> {
-    if needs_modification(&input) {
-        Cow::Owned(modify(&input))  // Clone only if needed
-    } else {
-        input  // No clone
-    }
-}
-```
-
-## Detecting Excessive Clones
-
-```toml
-# Cargo.toml
-[lints.clippy]
-clone_on_copy = "warn"
-clone_on_ref_ptr = "warn"
-redundant_clone = "warn"
-```
-
-## See Also
-
-- [own-borrow-over-clone](./own-borrow-over-clone.md) - Borrowing patterns
-- [own-cow-conditional](./own-cow-conditional.md) - Clone on write
-- [own-arc-shared](./own-arc-shared.md) - Shared ownership

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