agy-superpowers 5.2.2 → 5.2.3

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

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

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

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

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

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