agy-superpowers 5.1.4 → 5.1.6

package/template/agent/skills/rust-developer/references/rust-rules/name-to-expensive.md

@@ -0,0 +1,118 @@
+# name-to-expensive
+
+> Use `to_` prefix for expensive conversions that allocate or compute
+
+## Why It Matters
+
+The `to_` prefix signals "this conversion has a cost"—typically allocation, cloning, or computation. Callers know to consider caching the result or avoiding repeated calls. This contrasts with `as_` (free reference conversion) and `into_` (ownership transfer).
+
+## Bad
+
+```rust
+impl Name {
+    // Misleading: suggests expensive operation
+    fn as_uppercase(&self) -> String {
+        self.0.to_uppercase()  // Allocates!
+    }
+    
+    // Misleading: suggests cheap reference
+    fn get_string(&self) -> String {
+        self.0.clone()  // Allocates!
+    }
+}
+```
+
+## Good
+
+```rust
+impl Name {
+    // to_ = allocates/computes
+    fn to_uppercase(&self) -> String {
+        self.0.to_uppercase()
+    }
+    
+    // to_ = creates new value
+    fn to_string(&self) -> String {
+        self.0.clone()
+    }
+    
+    // as_ = free reference (cheap)
+    fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+```
+
+## Standard Library Examples
+
+```rust
+// to_ methods - all allocate or compute
+let s: String = slice.to_vec();           // Allocates Vec
+let s: String = "hello".to_string();      // Allocates String
+let s: String = "HELLO".to_lowercase();   // Allocates new String
+let s: String = path.to_string_lossy().into_owned();  // May allocate
+
+// Contrast with as_ methods - all are free
+let slice: &[u8] = s.as_bytes();          // Just reinterpret
+let str_ref: &str = string.as_str();      // Just reference
+let path: &Path = Path::new("foo");       // Just reference
+```
+
+## Conversion Method Prefixes
+
+| Prefix | Cost | Ownership | Example |
+|--------|------|-----------|---------|
+| `as_` | Free (O(1)) | Borrows `&T` | `as_str()`, `as_bytes()` |
+| `to_` | Allocates/Computes | Creates new | `to_string()`, `to_vec()` |
+| `into_` | Usually free | Takes ownership | `into_inner()`, `into_vec()` |
+
+## Custom Types
+
+```rust
+struct Email(String);
+
+impl Email {
+    // Cheap: just returns reference
+    fn as_str(&self) -> &str {
+        &self.0
+    }
+    
+    // Expensive: allocates
+    fn to_lowercase(&self) -> Email {
+        Email(self.0.to_lowercase())
+    }
+    
+    // Expensive: allocates
+    fn to_display_format(&self) -> String {
+        format!("<{}>", self.0)
+    }
+    
+    // Ownership transfer: usually cheap
+    fn into_string(self) -> String {
+        self.0
+    }
+}
+```
+
+## to_owned() Pattern
+
+```rust
+// to_owned() for getting owned version of borrowed data
+let borrowed: &str = "hello";
+let owned: String = borrowed.to_owned();  // Allocates
+
+let borrowed: &[i32] = &[1, 2, 3];
+let owned: Vec<i32> = borrowed.to_owned();  // Allocates
+
+// ToOwned trait
+trait ToOwned {
+    type Owned;
+    fn to_owned(&self) -> Self::Owned;
+}
+```
+
+## See Also
+
+- [name-as-free](./name-as-free.md) - Free reference conversions
+- [name-into-ownership](./name-into-ownership.md) - Ownership transfer
+- [own-cow-conditional](./own-cow-conditional.md) - Avoiding unnecessary allocations

package/template/agent/skills/rust-developer/references/rust-rules/name-type-param-single.md

@@ -0,0 +1,92 @@
+# name-type-param-single
+
+> Use single uppercase letters for type parameters: `T`, `E`, `K`, `V`
+
+## Why It Matters
+
+Generic type parameters conventionally use single uppercase letters. This keeps signatures concise and follows established conventions that readers instantly recognize. `T` for "type", `E` for "error", `K` for "key", `V` for "value" are universal in Rust.
+
+## Bad
+
+```rust
+// Verbose type parameters
+struct Container<ElementType> {
+    items: Vec<ElementType>,
+}
+
+fn process<InputType, OutputType>(input: InputType) -> OutputType { ... }
+
+// Lowercase - looks like lifetime
+struct Wrapper<t> { ... }  // Confusing
+```
+
+## Good
+
+```rust
+// Single uppercase letters
+struct Container<T> {
+    items: Vec<T>,
+}
+
+fn process<I, O>(input: I) -> O { ... }
+
+// Standard conventions
+struct HashMap<K, V> { ... }     // K=Key, V=Value
+enum Result<T, E> { ... }         // T=Type, E=Error
+enum Option<T> { ... }            // T=Type
+struct Ref<'a, T> { ... }        // Lifetime + Type
+```
+
+## Standard Type Parameter Names
+
+| Parameter | Meaning | Example |
+|-----------|---------|---------|
+| `T` | Type (generic) | `Vec<T>` |
+| `E` | Error | `Result<T, E>` |
+| `K` | Key | `HashMap<K, V>` |
+| `V` | Value | `HashMap<K, V>` |
+| `I` | Input / Item | `Iterator<Item = I>` |
+| `O` | Output | `Fn(I) -> O` |
+| `R` | Return / Result | `fn() -> R` |
+| `S` | State | `StateMachine<S>` |
+| `A` | Allocator | `Vec<T, A>` |
+| `F` | Function | `map<F>(f: F)` |
+
+## Multiple Type Parameters
+
+```rust
+// Use related letters
+fn transform<I, O, E>(input: I) -> Result<O, E>
+where
+    I: Input,
+    O: Output,
+    E: Error,
+{ ... }
+
+// Or sequential: T, U, V
+fn combine<T, U, V>(a: T, b: U) -> V { ... }
+
+// Descriptive only when many parameters need clarity
+struct Query<Db, Row, Err> { ... }
+```
+
+## Trait Bounds
+
+```rust
+// Keep type params short, move complexity to where clause
+fn process<T, E>(value: T) -> Result<T, E>
+where
+    T: Clone + Debug + Send + Sync,
+    E: Error + From<IoError>,
+{ ... }
+
+// Not inline
+fn process<T: Clone + Debug + Send + Sync, E: Error + From<IoError>>(value: T) -> Result<T, E>
+// Too long!
+```
+
+## See Also
+
+- [name-lifetime-short](./name-lifetime-short.md) - Lifetime parameter naming
+- [name-types-camel](./name-types-camel.md) - Concrete type naming
+- [type-generic-bounds](./type-generic-bounds.md) - Trait bounds

package/template/agent/skills/rust-developer/references/rust-rules/name-types-camel.md

@@ -0,0 +1,65 @@
+# name-types-camel
+
+> Use `UpperCamelCase` for types, traits, and enum names
+
+## Why It Matters
+
+Rust's naming conventions are enforced by the compiler and linter. Consistent naming makes code immediately recognizable—you know `HttpClient` is a type, `send_request` is a function. Violating conventions triggers warnings and makes code harder to read.
+
+## Bad
+
+```rust
+// Lowercase types - compiler warns
+struct http_client { ... }  // warning: type `http_client` should have an upper camel case name
+trait serializable { ... }  // warning
+enum response_type { ... }  // warning
+
+// Screaming case for types
+struct HTTP_CLIENT { ... }  // Not idiomatic
+```
+
+## Good
+
+```rust
+// UpperCamelCase for all types
+struct HttpClient { ... }
+trait Serializable { ... }
+enum ResponseType { ... }
+
+// Compound words
+struct TcpConnection { ... }
+struct IoError { ... }
+struct FileReader { ... }
+
+// Generic types
+struct HashMap<K, V> { ... }
+struct Result<T, E> { ... }
+```
+
+## Acronyms
+
+```rust
+// Treat acronyms as words (capitalize first letter only)
+struct HttpServer { ... }      // Not HTTPServer
+struct JsonParser { ... }      // Not JSONParser
+struct Uuid { ... }            // Not UUID
+struct TcpStream { ... }       // Not TCPStream
+
+// Exception: Two-letter acronyms can be all caps
+struct IOError { ... }         // Acceptable
+struct IoError { ... }         // Also acceptable (preferred)
+```
+
+## Type Aliases
+
+```rust
+// Type aliases also use UpperCamelCase
+type Result<T> = std::result::Result<T, Error>;
+type BoxedFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;
+```
+
+## See Also
+
+- [name-variants-camel](./name-variants-camel.md) - Enum variant naming
+- [name-funcs-snake](./name-funcs-snake.md) - Function naming
+- [name-acronym-word](./name-acronym-word.md) - Acronym handling

package/template/agent/skills/rust-developer/references/rust-rules/name-variants-camel.md

@@ -0,0 +1,101 @@
+# name-variants-camel
+
+> Use `UpperCamelCase` for enum variants
+
+## Why It Matters
+
+Enum variants follow the same naming convention as types—`UpperCamelCase`. This distinguishes them from fields, variables, and functions. The compiler warns on violations, and consistent naming helps readers instantly recognize variant names.
+
+## Bad
+
+```rust
+enum Status {
+    pending,       // warning: variant `pending` should have an upper camel case name
+    in_progress,   // warning
+    COMPLETED,     // Not idiomatic
+}
+
+enum Color {
+    RED,           // Screaming case - not Rust style
+    GREEN,
+    BLUE,
+}
+```
+
+## Good
+
+```rust
+enum Status {
+    Pending,
+    InProgress,
+    Completed,
+    Failed,
+}
+
+enum Color {
+    Red,
+    Green,
+    Blue,
+    Custom(u8, u8, u8),
+}
+
+enum HttpMethod {
+    Get,
+    Post,
+    Put,
+    Delete,
+    Patch,
+}
+```
+
+## Variants with Data
+
+```rust
+enum Message {
+    // Unit variant
+    Quit,
+    
+    // Tuple variant
+    Move(i32, i32),
+    
+    // Struct variant
+    Write { text: String },
+    
+    // Named fields
+    ChangeColor {
+        red: u8,
+        green: u8,
+        blue: u8,
+    },
+}
+```
+
+## Variant Naming Tips
+
+```rust
+// Be specific
+enum Error {
+    NotFound,           // Good: specific
+    PermissionDenied,   // Good: specific
+    Error,              // Bad: vague
+}
+
+// Avoid redundant type name in variant
+enum ConnectionState {
+    Connected,          // Good
+    Disconnected,       // Good
+    ConnectionError,    // Bad: redundant "Connection"
+}
+
+// Use None/Some pattern for Option-like enums
+enum MaybeValue<T> {
+    Some(T),
+    None,
+}
+```
+
+## See Also
+
+- [name-types-camel](./name-types-camel.md) - Type naming
+- [api-non-exhaustive](./api-non-exhaustive.md) - Forward-compatible enums
+- [type-enum-states](./type-enum-states.md) - State machine enums

package/template/agent/skills/rust-developer/references/rust-rules/opt-bounds-check.md

@@ -0,0 +1,161 @@
+# opt-bounds-check
+
+> Use iterators and patterns that eliminate bounds checks in hot paths
+
+## Why It Matters
+
+Rust's safety guarantees require bounds checking on array/slice indexing. In tight loops, these checks can cause measurable overhead (branch mispredictions, preventing vectorization). Patterns like iterators, `get_unchecked`, and index splitting can eliminate these checks while maintaining safety.
+
+## Bad
+
+```rust
+fn sum_products(a: &[f64], b: &[f64]) -> f64 {
+    let mut sum = 0.0;
+    for i in 0..a.len() {
+        sum += a[i] * b[i];  // Two bounds checks per iteration
+    }
+    sum
+}
+
+fn apply_filter(data: &mut [u8], kernel: &[u8; 3]) {
+    for i in 1..data.len() - 1 {
+        // Three bounds checks per iteration
+        data[i] = (data[i - 1] + data[i] + data[i + 1]) / 3;
+    }
+}
+```
+
+## Good
+
+```rust
+fn sum_products(a: &[f64], b: &[f64]) -> f64 {
+    // Iterator zips - no bounds checks, vectorizes well
+    a.iter().zip(b.iter()).map(|(x, y)| x * y).sum()
+}
+
+fn apply_filter(data: &mut [u8]) {
+    // Windows pattern - no bounds checks
+    for window in data.windows(3) {
+        // window[0], window[1], window[2] are all valid
+    }
+    
+    // Or use chunks
+    for chunk in data.chunks_exact(4) {
+        process_simd(chunk);
+    }
+}
+```
+
+## Iterator Patterns
+
+```rust
+// All of these avoid bounds checks:
+
+// zip - parallel iteration
+for (a, b) in xs.iter().zip(ys.iter()) { ... }
+
+// enumerate - index + value  
+for (i, x) in data.iter().enumerate() { ... }
+
+// windows - sliding window
+for window in data.windows(3) { ... }
+
+// chunks - fixed-size groups
+for chunk in data.chunks(4) { ... }
+for chunk in data.chunks_exact(4) { ... }  // Guarantees exact size
+
+// split_at - divide slice
+let (left, right) = data.split_at(mid);
+```
+
+## Split for Parallel Access
+
+```rust
+fn parallel_sum(data: &[i32]) -> i32 {
+    // Split into independent chunks
+    let (left, right) = data.split_at(data.len() / 2);
+    
+    // Process chunks without bounds checks
+    let sum_left: i32 = left.iter().sum();
+    let sum_right: i32 = right.iter().sum();
+    
+    sum_left + sum_right
+}
+```
+
+## get_unchecked for Proven Safety
+
+```rust
+fn matrix_multiply(a: &[f64], b: &[f64], c: &mut [f64], n: usize) {
+    assert!(a.len() >= n * n);
+    assert!(b.len() >= n * n);
+    assert!(c.len() >= n * n);
+    
+    for i in 0..n {
+        for j in 0..n {
+            let mut sum = 0.0;
+            for k in 0..n {
+                // SAFETY: bounds verified by asserts above
+                unsafe {
+                    sum += a.get_unchecked(i * n + k) 
+                         * b.get_unchecked(k * n + j);
+                }
+            }
+            // SAFETY: bounds verified by asserts above
+            unsafe {
+                *c.get_unchecked_mut(i * n + j) = sum;
+            }
+        }
+    }
+}
+```
+
+## Slice Patterns
+
+```rust
+fn process_header(data: &[u8]) -> Option<Header> {
+    // Slice pattern - single length check, no per-field checks
+    let [a, b, c, d, rest @ ..] = data else {
+        return None;
+    };
+    
+    Some(Header {
+        magic: *a,
+        version: *b,
+        flags: u16::from_le_bytes([*c, *d]),
+        payload: rest,
+    })
+}
+```
+
+## Verify Bounds Check Elimination
+
+```bash
+# Check generated assembly
+cargo asm --release my_crate::hot_function
+
+# Look for 'cmp' and 'ja'/'jbe' instructions near array access
+# If eliminated, you'll see direct memory access
+```
+
+## When to Accept Bounds Checks
+
+```rust
+// Random access patterns - checks unavoidable
+fn random_lookup(data: &[u8], indices: &[usize]) -> Vec<u8> {
+    indices.iter()
+        .filter_map(|&i| data.get(i).copied())  // Checked, but necessary
+        .collect()
+}
+
+// Infrequent access - overhead negligible
+fn get_config(&self, key: &str) -> Option<&Value> {
+    self.config.get(key)  // Fine, not hot path
+}
+```
+
+## See Also
+
+- [opt-simd-portable](./opt-simd-portable.md) - SIMD requires unchecked access
+- [opt-cache-friendly](./opt-cache-friendly.md) - Cache-efficient patterns
+- [perf-profile-first](./perf-profile-first.md) - Identify actual hot paths