agy-superpowers 5.2.2 → 5.2.4

package/template/agent/skills/rust-developer/references/rust-rules/own-copy-small.md

@@ -1,124 +0,0 @@
-# own-copy-small
-
-> Implement `Copy` for small, simple types
-
-## Why It Matters
-
-Types that implement `Copy` are implicitly duplicated on assignment instead of moved. This eliminates the need for explicit `.clone()` calls and makes the code more ergonomic. For small types (generally ≤16 bytes), copying is as fast or faster than moving a pointer.
-
-## Bad
-
-```rust
-// Small type without Copy - requires explicit clone
-#[derive(Clone, Debug)]
-struct Point {
-    x: f64,
-    y: f64,
-}
-
-fn distance(p1: Point, p2: Point) -> f64 {
-    ((p2.x - p1.x).powi(2) + (p2.y - p1.y).powi(2)).sqrt()
-}
-
-let origin = Point { x: 0.0, y: 0.0 };
-let target = Point { x: 3.0, y: 4.0 };
-
-let d1 = distance(origin.clone(), target.clone()); // Tedious
-let d2 = distance(origin.clone(), target.clone()); // Every use needs clone
-// origin and target still usable but verbose
-```
-
-## Good
-
-```rust
-// Small type with Copy - implicit duplication
-#[derive(Clone, Copy, Debug)]
-struct Point {
-    x: f64,
-    y: f64,
-}
-
-fn distance(p1: Point, p2: Point) -> f64 {
-    ((p2.x - p1.x).powi(2) + (p2.y - p1.y).powi(2)).sqrt()
-}
-
-let origin = Point { x: 0.0, y: 0.0 };
-let target = Point { x: 3.0, y: 4.0 };
-
-let d1 = distance(origin, target); // Implicitly copied
-let d2 = distance(origin, target); // Still works!
-// origin and target remain valid
-```
-
-## Copy Requirements
-
-A type can implement `Copy` only if:
-1. All fields implement `Copy`
-2. No custom `Drop` implementation
-3. No heap-allocated data (`String`, `Vec`, `Box`, etc.)
-
-```rust
-// ✅ Can be Copy
-#[derive(Clone, Copy)]
-struct Color {
-    r: u8,
-    g: u8,
-    b: u8,
-    a: u8,
-}
-
-// ❌ Cannot be Copy - contains String
-#[derive(Clone)]
-struct Person {
-    name: String,  // String is not Copy
-    age: u32,
-}
-
-// ❌ Cannot be Copy - has Drop
-struct FileHandle {
-    fd: i32,
-}
-impl Drop for FileHandle {
-    fn drop(&mut self) { /* close file */ }
-}
-```
-
-## Size Guidelines
-
-| Size | Recommendation |
-|------|----------------|
-| ≤ 16 bytes | Implement `Copy` |
-| 17-64 bytes | Consider `Copy`, benchmark if critical |
-| > 64 bytes | Probably don't, prefer references |
-
-```rust
-use std::mem::size_of;
-
-#[derive(Clone, Copy)]
-struct SmallId(u64); // 8 bytes ✅
-
-#[derive(Clone, Copy)]
-struct Rect { x: f32, y: f32, w: f32, h: f32 } // 16 bytes ✅
-
-#[derive(Clone)] // No Copy - 72 bytes
-struct Transform {
-    matrix: [[f64; 3]; 3], // 72 bytes, too large
-}
-```
-
-## Common Copy Types
-
-Standard library types that are `Copy`:
-- All primitives: `i32`, `f64`, `bool`, `char`, etc.
-- References: `&T`, `&mut T`
-- Raw pointers: `*const T`, `*mut T`
-- Function pointers: `fn(T) -> U`
-- Tuples of `Copy` types: `(i32, f64)`
-- Arrays of `Copy` types: `[u8; 32]`
-- `Option<T>` where `T: Copy`
-- `PhantomData<T>`
-
-## See Also
-
-- [own-clone-explicit](./own-clone-explicit.md) - When Clone without Copy is appropriate
-- [type-newtype-ids](./type-newtype-ids.md) - Newtype pattern often uses Copy

package/template/agent/skills/rust-developer/references/rust-rules/own-cow-conditional.md

@@ -1,135 +0,0 @@
-# own-cow-conditional
-
-> Use `Cow<'a, T>` for conditional ownership
-
-## Why It Matters
-
-`Cow` (Clone-on-Write) lets you avoid allocations when you *might* need to own data but usually don't. It holds either a borrowed reference or an owned value, cloning only when mutation is needed.
-
-## Bad
-
-```rust
-// Always allocates, even when input doesn't need modification
-fn normalize_path(path: &str) -> String {
-    if path.contains("//") {
-        path.replace("//", "/")  // Allocation needed
-    } else {
-        path.to_string()  // Unnecessary allocation!
-    }
-}
-
-// Always clones the error message
-fn format_error(code: u32) -> String {
-    match code {
-        404 => "Not Found".to_string(),      // Unnecessary!
-        500 => "Internal Error".to_string(), // Unnecessary!
-        _ => format!("Error {}", code),      // This one needs allocation
-    }
-}
-```
-
-## Good
-
-```rust
-use std::borrow::Cow;
-
-// Only allocates when needed
-fn normalize_path(path: &str) -> Cow<'_, str> {
-    if path.contains("//") {
-        Cow::Owned(path.replace("//", "/"))  // Allocate
-    } else {
-        Cow::Borrowed(path)  // Zero-cost borrow
-    }
-}
-
-// Static strings stay borrowed
-fn format_error(code: u32) -> Cow<'static, str> {
-    match code {
-        404 => Cow::Borrowed("Not Found"),      // No allocation
-        500 => Cow::Borrowed("Internal Error"), // No allocation
-        _ => Cow::Owned(format!("Error {}", code)), // Allocate only for unknown
-    }
-}
-```
-
-## Real-World Example from ripgrep
-
-```rust
-// https://github.com/BurntSushi/ripgrep/blob/master/crates/globset/src/pathutil.rs
-pub(crate) fn file_name<'a>(path: &Cow<'a, [u8]>) -> Option<Cow<'a, [u8]>> {
-    let last_slash = path.rfind_byte(b'/').map(|i| i + 1).unwrap_or(0);
-    match *path {
-        Cow::Borrowed(path) => Some(Cow::Borrowed(&path[last_slash..])),
-        Cow::Owned(ref path) => {
-            let mut path = path.clone();
-            path.drain_bytes(..last_slash);
-            Some(Cow::Owned(path))
-        }
-    }
-}
-```
-
-## Clone-on-Write Pattern
-
-```rust
-use std::borrow::Cow;
-
-fn process_text(text: Cow<'_, str>) -> Cow<'_, str> {
-    if text.contains("bad_word") {
-        // to_mut() clones if borrowed, returns &mut if owned
-        let mut owned = text.into_owned();
-        owned = owned.replace("bad_word", "***");
-        Cow::Owned(owned)
-    } else {
-        text  // Pass through unchanged
-    }
-}
-
-// Usage
-let borrowed: Cow<str> = Cow::Borrowed("hello world");
-let result = process_text(borrowed);  // No allocation!
-
-let with_bad: Cow<str> = Cow::Borrowed("hello bad_word");
-let result = process_text(with_bad);  // Allocates only here
-```
-
-## Cow with Collections
-
-```rust
-use std::borrow::Cow;
-
-// Mixed borrowed/owned in a collection
-fn collect_errors<'a>(
-    static_errors: &[&'static str],
-    dynamic_errors: Vec<String>,
-) -> Vec<Cow<'a, str>> {
-    let mut errors: Vec<Cow<str>> = Vec::new();
-    
-    // Static strings - no allocation
-    for &e in static_errors {
-        errors.push(Cow::Borrowed(e));
-    }
-    
-    // Dynamic strings - take ownership
-    for e in dynamic_errors {
-        errors.push(Cow::Owned(e));
-    }
-    
-    errors
-}
-```
-
-## When to Use Cow
-
-| Situation | Use Cow? |
-|-----------|----------|
-| Usually borrow, sometimes own | Yes |
-| Always need owned data | No, just use owned type |
-| Always borrow | No, just use reference |
-| Hot path, avoiding all allocations | Yes |
-| Returning static strings or formatted | Yes |
-
-## See Also
-
-- [own-borrow-over-clone](own-borrow-over-clone.md) - Prefer borrowing over cloning
-- [mem-avoid-format](mem-avoid-format.md) - Avoid format! when possible

package/template/agent/skills/rust-developer/references/rust-rules/own-lifetime-elision.md

@@ -1,134 +0,0 @@
-# own-lifetime-elision
-
-> Rely on lifetime elision rules; add explicit lifetimes only when required
-
-## Why It Matters
-
-Rust's lifetime elision rules handle most common borrowing patterns automatically. Adding explicit lifetimes where they're not needed clutters code without adding clarity. However, understanding when elision applies helps you know when explicit lifetimes are truly necessary.
-
-## Bad
-
-```rust
-// Unnecessary explicit lifetimes - elision handles these
-fn first_word<'a>(s: &'a str) -> &'a str {
-    s.split_whitespace().next().unwrap_or("")
-}
-
-fn get_name<'a>(person: &'a Person) -> &'a str {
-    &person.name
-}
-
-impl<'a> Display for Wrapper<'a> {
-    fn fmt<'b>(&'b self, f: &'b mut Formatter<'_>) -> fmt::Result {
-        write!(f, "{}", self.0)
-    }
-}
-```
-
-## Good
-
-```rust
-// Let elision do its job
-fn first_word(s: &str) -> &str {
-    s.split_whitespace().next().unwrap_or("")
-}
-
-fn get_name(person: &Person) -> &str {
-    &person.name
-}
-
-impl Display for Wrapper<'_> {
-    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
-        write!(f, "{}", self.0)
-    }
-}
-```
-
-## The Three Elision Rules
-
-1. **Each input reference gets its own lifetime:**
-   ```rust
-   fn foo(x: &str, y: &str) 
-   // becomes
-   fn foo<'a, 'b>(x: &'a str, y: &'b str)
-   ```
-
-2. **One input reference → output gets same lifetime:**
-   ```rust
-   fn foo(x: &str) -> &str
-   // becomes  
-   fn foo<'a>(x: &'a str) -> &'a str
-   ```
-
-3. **Method with `&self`/`&mut self` → output gets self's lifetime:**
-   ```rust
-   fn foo(&self, x: &str) -> &str
-   // becomes
-   fn foo<'a, 'b>(&'a self, x: &'b str) -> &'a str
-   ```
-
-## When Explicit Lifetimes ARE Required
-
-```rust
-// Multiple input references, output could come from either
-fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
-    if x.len() > y.len() { x } else { y }
-}
-
-// Struct holding references
-struct Parser<'input> {
-    source: &'input str,
-    position: usize,
-}
-
-// Multiple distinct lifetimes needed
-struct Context<'s, 'c> {
-    source: &'s str,
-    cache: &'c mut Cache,
-}
-
-// Static lifetime for constants
-fn get_default() -> &'static str {
-    "default"
-}
-```
-
-## Anonymous Lifetime `'_`
-
-Use `'_` to let the compiler infer while being explicit about the presence of a lifetime:
-
-```rust
-// In struct definitions
-impl Iterator for Parser<'_> {
-    type Item = Token;
-    fn next(&mut self) -> Option<Self::Item> { ... }
-}
-
-// In function signatures where it adds clarity
-fn parse(input: &str) -> Result<Ast<'_>, Error> { ... }
-
-// Especially useful in trait bounds
-fn process(data: &impl AsRef<str>) -> Cow<'_, str> { ... }
-```
-
-## Common Patterns
-
-```rust
-// ✅ Elision works
-fn trim(s: &str) -> &str { s.trim() }
-fn first(v: &[i32]) -> Option<&i32> { v.first() }
-fn name(&self) -> &str { &self.name }
-
-// ❌ Elision fails - multiple inputs, ambiguous output
-fn pick(a: &str, b: &str, first: bool) -> &str // Error!
-
-// ✅ Fixed with explicit lifetime
-fn pick<'a>(a: &'a str, b: &'a str, first: bool) -> &'a str {
-    if first { a } else { b }
-}
-```
-
-## See Also
-
-- [own-borrow-over-clone](./own-borrow-over-clone.md) - Prefer borrowing to avoid ownership issues
-- [api-impl-asref](./api-impl-asref.md) - Generic borrowing with AsRef

package/template/agent/skills/rust-developer/references/rust-rules/own-move-large.md

@@ -1,134 +0,0 @@
-# own-move-large
-
-> Move large types instead of copying; use `Box` if moves are expensive
-
-## Why It Matters
-
-In Rust, "moving" a value means copying its bytes to a new location and invalidating the old one. For large types (hundreds of bytes), this memcpy can be expensive. Boxing large types reduces move cost to copying a single pointer (8 bytes), making moves cheap regardless of the actual data size.
-
-## Bad
-
-```rust
-// Large struct moved repeatedly = expensive memcpy each time
-struct GameState {
-    board: [[Cell; 100]; 100],  // 10,000 cells
-    history: [Move; 1000],       // 1,000 moves
-    players: [Player; 4],        // Player data
-    // Total: potentially tens of KB
-}
-
-fn process_state(state: GameState) -> GameState {
-    // Moving ~40KB+ of data
-    let mut new_state = state;  // Memcpy here
-    new_state.apply_rules();
-    new_state  // Memcpy on return
-}
-
-let state = GameState::new();
-let state = process_state(state);  // Two large memcpys
-```
-
-## Good
-
-```rust
-// Box reduces move cost to 8 bytes
-struct GameState {
-    board: Box<[[Cell; 100]; 100]>,  // Pointer to heap
-    history: Vec<Move>,               // Already heap-allocated
-    players: [Player; 4],
-}
-
-fn process_state(mut state: GameState) -> GameState {
-    // Moving just pointers + small inline data
-    state.apply_rules();
-    state  // Cheap move
-}
-
-// Or use Box at call site for one-off cases
-fn process_large(state: Box<LargeStruct>) -> Box<LargeStruct> {
-    // 8-byte move regardless of LargeStruct size
-    state
-}
-```
-
-## When to Box
-
-| Type Size | Move Frequency | Recommendation |
-|-----------|----------------|----------------|
-| < 128 bytes | Any | Don't box |
-| 128-512 bytes | Rare | Probably don't box |
-| 128-512 bytes | Frequent | Consider boxing |
-| > 512 bytes | Any | Box or use references |
-| > 4KB | Any | Definitely box |
-
-## Stack vs Heap Tradeoffs
-
-```rust
-// Stack: fast allocation, limited size, moves copy bytes
-struct StackHeavy {
-    data: [u8; 4096],  // 4KB on stack
-}
-
-// Heap: allocation cost, unlimited size, moves copy pointer
-struct HeapLight {
-    data: Box<[u8; 4096]>,  // 8 bytes on stack, 4KB on heap
-}
-
-// Measure with size_of
-use std::mem::size_of;
-assert_eq!(size_of::<StackHeavy>(), 4096);
-assert_eq!(size_of::<HeapLight>(), 8);
-```
-
-## Alternative: References
-
-When you don't need ownership transfer, use references:
-
-```rust
-// Best: no move at all
-fn analyze_state(state: &GameState) -> Analysis {
-    // Borrows state, no copying
-    compute_analysis(state)
-}
-
-// Mutable borrow for in-place modification
-fn update_state(state: &mut GameState) {
-    state.tick();
-}
-```
-
-## Pattern: Builder Returns Boxed
-
-```rust
-impl LargeConfig {
-    pub fn builder() -> ConfigBuilder {
-        ConfigBuilder::default()
-    }
-}
-
-impl ConfigBuilder {
-    // Return boxed to avoid large move
-    pub fn build(self) -> Box<LargeConfig> {
-        Box::new(LargeConfig {
-            // ... fields from builder
-        })
-    }
-}
-```
-
-## Profile First
-
-Don't prematurely optimize. Use tools to identify if moves are actually a bottleneck:
-
-```rust
-// Check type sizes
-println!("Size of GameState: {}", std::mem::size_of::<GameState>());
-
-// Profile with cargo flamegraph or perf to find hot memcpys
-```
-
-## See Also
-
-- [own-copy-small](./own-copy-small.md) - Cheap types should be Copy
-- [mem-box-large-variant](./mem-box-large-variant.md) - Boxing enum variants
-- [perf-profile-first](./perf-profile-first.md) - Measure before optimizing

package/template/agent/skills/rust-developer/references/rust-rules/own-mutex-interior.md

@@ -1,105 +0,0 @@
-# own-mutex-interior
-
-> Use `Mutex<T>` for interior mutability across threads
-
-## Why It Matters
-
-When you need shared mutable state across threads, `Mutex<T>` provides safe interior mutability with synchronization. Unlike `RefCell`, `Mutex` is `Send + Sync` and uses OS-level locking to ensure only one thread can access the data at a time.
-
-## Bad
-
-```rust
-use std::cell::RefCell;
-use std::sync::Arc;
-
-// RefCell is !Sync - this won't compile
-let shared = Arc::new(RefCell::new(vec![]));
-
-// ERROR: RefCell cannot be shared between threads safely
-std::thread::spawn({
-    let shared = shared.clone();
-    move || shared.borrow_mut().push(1)
-});
-```
-
-## Good
-
-```rust
-use std::sync::{Arc, Mutex};
-
-let shared = Arc::new(Mutex::new(vec![]));
-
-let handles: Vec<_> = (0..10).map(|i| {
-    let shared = shared.clone();
-    std::thread::spawn(move || {
-        let mut data = shared.lock().unwrap();
-        data.push(i);
-    })
-}).collect();
-
-for handle in handles {
-    handle.join().unwrap();
-}
-
-println!("{:?}", shared.lock().unwrap()); // All values present
-```
-
-## Mutex Poisoning
-
-If a thread panics while holding a lock, the mutex becomes "poisoned":
-
-```rust
-use std::sync::{Arc, Mutex};
-
-let mutex = Arc::new(Mutex::new(0));
-
-// Handle poisoning gracefully
-match mutex.lock() {
-    Ok(guard) => println!("Value: {}", *guard),
-    Err(poisoned) => {
-        // Recover the data anyway
-        let guard = poisoned.into_inner();
-        println!("Recovered value: {}", *guard);
-    }
-}
-
-// Or ignore poisoning (use with caution)
-let guard = mutex.lock().unwrap_or_else(|e| e.into_inner());
-```
-
-## Prefer parking_lot::Mutex
-
-For better performance, consider `parking_lot::Mutex`:
-
-```rust
-use parking_lot::Mutex;
-use std::sync::Arc;
-
-let shared = Arc::new(Mutex::new(vec![]));
-
-// No poisoning, no Result to unwrap
-let mut data = shared.lock();
-data.push(42);
-// Lock automatically released when guard drops
-```
-
-Benefits of `parking_lot`:
-- No poisoning (returns guard directly)
-- Smaller size (1 byte vs 40+ bytes)
-- Better performance under contention
-- Fair locking option available
-
-## When to Use What
-
-| Type | Threading | Overhead | Use Case |
-|------|-----------|----------|----------|
-| `RefCell<T>` | Single | Minimal | Interior mutability, same thread |
-| `Mutex<T>` | Multi | Locking | Shared mutable state across threads |
-| `RwLock<T>` | Multi | Locking | Many readers, few writers |
-| `parking_lot::Mutex` | Multi | Less | Drop-in std::Mutex replacement |
-
-## See Also
-
-- [own-rwlock-readers](./own-rwlock-readers.md) - When reads dominate writes
-- [own-refcell-interior](./own-refcell-interior.md) - Single-threaded alternative
-- [async-no-lock-await](./async-no-lock-await.md) - Avoiding locks across await points

package/template/agent/skills/rust-developer/references/rust-rules/own-rc-single-thread.md

@@ -1,65 +0,0 @@
-# own-rc-single-thread
-
-> Use `Rc<T>` for shared ownership in single-threaded contexts
-
-## Why It Matters
-
-`Rc<T>` (Reference Counted) provides shared ownership without the atomic overhead of `Arc<T>`. In single-threaded code, `Rc` is faster because it uses non-atomic reference counting. Using `Arc` when you don't need thread-safety wastes CPU cycles on unnecessary synchronization.
-
-## Bad
-
-```rust
-use std::sync::Arc;
-
-// Single-threaded application using Arc unnecessarily
-fn build_tree() -> Arc<Node> {
-    let root = Arc::new(Node::new("root"));
-    let child1 = Arc::new(Node::new("child1"));
-    let child2 = Arc::new(Node::new("child2"));
-    
-    // All in same thread, but paying atomic overhead
-    root.add_child(child1.clone());
-    root.add_child(child2.clone());
-    root
-}
-```
-
-Atomic operations have measurable overhead even without contention.
-
-## Good
-
-```rust
-use std::rc::Rc;
-
-// Single-threaded: use Rc for zero atomic overhead
-fn build_tree() -> Rc<Node> {
-    let root = Rc::new(Node::new("root"));
-    let child1 = Rc::new(Node::new("child1"));
-    let child2 = Rc::new(Node::new("child2"));
-    
-    root.add_child(child1.clone());
-    root.add_child(child2.clone());
-    root
-}
-
-// Compiler enforces single-thread: Rc is !Send + !Sync
-// Attempting to send across threads = compile error
-```
-
-## Decision Guide
-
-| Scenario | Use |
-|----------|-----|
-| Single-threaded, shared ownership | `Rc<T>` |
-| Multi-threaded, shared ownership | `Arc<T>` |
-| Single owner, might need multiple later | Start with `Rc`, upgrade if needed |
-| Library code, unknown threading model | `Arc<T>` (safer default) |
-
-## Evidence
-
-The Rust standard library itself uses `Rc` extensively in single-threaded contexts like the `std::rc` module documentation examples.
-
-## See Also
-
-- [own-arc-shared](./own-arc-shared.md) - When you need thread-safe sharing
-- [own-refcell-interior](./own-refcell-interior.md) - Combining Rc with interior mutability