agy-superpowers 5.1.4 → 5.1.5

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

package/template/agent/skills/rust-developer/references/rust-rules/opt-cache-friendly.md

@@ -0,0 +1,187 @@
+# opt-cache-friendly
+
+> Organize data for cache-efficient access patterns
+
+## Why It Matters
+
+Cache misses are expensive—a L3 cache miss costs ~100+ cycles vs ~4 cycles for L1 hit. Data layout and access patterns determine cache efficiency. Arrays of structs (AoS) vs structs of arrays (SoA), memory locality, and access patterns can make order-of-magnitude performance differences.
+
+## Bad
+
+```rust
+// Array of Structs (AoS) - poor cache use when accessing one field
+struct Particle {
+    position: [f32; 3],  // 12 bytes
+    velocity: [f32; 3],  // 12 bytes
+    mass: f32,           // 4 bytes
+    id: u64,             // 8 bytes
+    flags: u8,           // 1 byte + padding
+    // Total: 40 bytes per particle
+}
+
+fn update_positions(particles: &mut [Particle], dt: f32) {
+    for p in particles {
+        // Access position and velocity - 24 bytes
+        // But loads 40-byte struct per particle
+        // 16 bytes wasted per cache line load
+        p.position[0] += p.velocity[0] * dt;
+        p.position[1] += p.velocity[1] * dt;
+        p.position[2] += p.velocity[2] * dt;
+    }
+}
+```
+
+## Good
+
+```rust
+// Struct of Arrays (SoA) - cache-efficient for field access
+struct Particles {
+    positions_x: Vec<f32>,
+    positions_y: Vec<f32>,
+    positions_z: Vec<f32>,
+    velocities_x: Vec<f32>,
+    velocities_y: Vec<f32>,
+    velocities_z: Vec<f32>,
+    masses: Vec<f32>,
+    ids: Vec<u64>,
+    flags: Vec<u8>,
+}
+
+fn update_positions(p: &mut Particles, dt: f32) {
+    // Access contiguous memory - perfect cache utilization
+    for (px, vx) in p.positions_x.iter_mut().zip(&p.velocities_x) {
+        *px += vx * dt;
+    }
+    for (py, vy) in p.positions_y.iter_mut().zip(&p.velocities_y) {
+        *py += vy * dt;
+    }
+    for (pz, vz) in p.positions_z.iter_mut().zip(&p.velocities_z) {
+        *pz += vz * dt;
+    }
+}
+```
+
+## Hot/Cold Splitting
+
+```rust
+// Separate frequently and rarely accessed fields
+struct EntityHot {
+    position: [f32; 3],
+    velocity: [f32; 3],
+    // Hot data - accessed every frame
+}
+
+struct EntityCold {
+    name: String,
+    creation_time: Instant,
+    metadata: HashMap<String, Value>,
+    // Cold data - rarely accessed
+}
+
+struct Entities {
+    hot: Vec<EntityHot>,
+    cold: Vec<EntityCold>,
+}
+
+// Hot loop touches only hot data
+fn update(entities: &mut Entities, dt: f32) {
+    for e in &mut entities.hot {
+        e.position[0] += e.velocity[0] * dt;
+        // Cold data stays out of cache
+    }
+}
+```
+
+## Prefetching
+
+```rust
+// Process in cache-line-sized chunks
+const CACHE_LINE: usize = 64;
+
+fn process_with_prefetch(data: &mut [u8]) {
+    for chunk in data.chunks_mut(CACHE_LINE) {
+        // Prefetch next chunk while processing current
+        // (automatic in many cases, manual for complex patterns)
+        process_chunk(chunk);
+    }
+}
+
+// Matrix multiplication - block for cache
+fn matmul_blocked(a: &[f64], b: &[f64], c: &mut [f64], n: usize) {
+    const BLOCK: usize = 32;  // Fits in L1 cache
+    
+    for i0 in (0..n).step_by(BLOCK) {
+        for j0 in (0..n).step_by(BLOCK) {
+            for k0 in (0..n).step_by(BLOCK) {
+                // Process BLOCK x BLOCK tile
+                for i in i0..min(i0 + BLOCK, n) {
+                    for j in j0..min(j0 + BLOCK, n) {
+                        // Inner loop operates on cached data
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+## Avoid Pointer Chasing
+
+```rust
+// Bad: linked list - random memory access
+struct Node {
+    value: i32,
+    next: Option<Box<Node>>,
+}
+
+fn sum_linked(head: &Node) -> i32 {
+    // Each node is a cache miss
+}
+
+// Good: contiguous vector
+fn sum_vector(data: &[i32]) -> i32 {
+    data.iter().sum()  // Sequential access, prefetcher happy
+}
+
+// Good: if graph needed, use indices
+struct Graph {
+    values: Vec<i32>,
+    edges: Vec<usize>,  // Indices into values
+}
+```
+
+## Memory Layout Attributes
+
+```rust
+// Ensure cache-line alignment
+#[repr(C, align(64))]
+struct CacheAligned {
+    data: [u8; 64],
+}
+
+// Prevent false sharing in concurrent code
+#[repr(C, align(64))]
+struct PaddedCounter {
+    value: AtomicU64,
+    _pad: [u8; 56],
+}
+```
+
+## Measuring Cache Performance
+
+```bash
+# Linux perf
+perf stat -e cache-references,cache-misses ./my_program
+
+# Detailed cache analysis
+perf stat -e L1-dcache-loads,L1-dcache-load-misses,LLC-loads,LLC-load-misses ./my_program
+
+# Cachegrind
+valgrind --tool=cachegrind ./my_program
+```
+
+## See Also
+
+- [mem-smaller-integers](./mem-smaller-integers.md) - Smaller data fits more in cache
+- [mem-box-large-variant](./mem-box-large-variant.md) - Keep enum sizes small
+- [opt-bounds-check](./opt-bounds-check.md) - Sequential access patterns