agy-superpowers 5.2.1 → 5.2.3

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

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

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