agy-superpowers 5.2.2 → 5.2.3

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

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

@@ -1,97 +0,0 @@
-# own-refcell-interior
-
-> Use `RefCell<T>` for interior mutability in single-threaded code
-
-## Why It Matters
-
-Rust's borrow checker enforces rules at compile time, but sometimes you need to mutate data through a shared reference. `RefCell<T>` moves borrow checking to runtime, allowing mutation through `&self`. This is essential for patterns like caches, lazy initialization, and observer patterns where compile-time borrowing is too restrictive.
-
-## Bad
-
-```rust
-struct Cache {
-    // Requires &mut self to update, breaking shared reference patterns
-    data: HashMap<String, String>,
-}
-
-impl Cache {
-    fn get_or_compute(&mut self, key: &str) -> &str {
-        // Caller needs &mut Cache, can't share cache reference
-        if !self.data.contains_key(key) {
-            self.data.insert(key.to_string(), expensive_compute(key));
-        }
-        &self.data[key]
-    }
-}
-```
-
-This forces exclusive access even for logically shared operations.
-
-## Good
-
-```rust
-use std::cell::RefCell;
-use std::collections::HashMap;
-
-struct Cache {
-    data: RefCell<HashMap<String, String>>,
-}
-
-impl Cache {
-    fn get_or_compute(&self, key: &str) -> String {
-        // Can mutate through &self
-        let mut data = self.data.borrow_mut();
-        if !data.contains_key(key) {
-            data.insert(key.to_string(), expensive_compute(key));
-        }
-        data[key].clone()
-    }
-}
-
-// Multiple references can coexist
-let cache = Cache::new();
-let ref1 = &cache;
-let ref2 = &cache;
-ref1.get_or_compute("key1");
-ref2.get_or_compute("key2");
-```
-
-## Common Pattern: Rc<RefCell<T>>
-
-```rust
-use std::rc::Rc;
-use std::cell::RefCell;
-
-// Shared mutable state in single-threaded code
-type SharedState = Rc<RefCell<AppState>>;
-
-fn create_handlers(state: SharedState) -> Vec<Box<dyn Fn()>> {
-    vec![
-        Box::new({
-            let state = state.clone();
-            move || state.borrow_mut().increment()
-        }),
-        Box::new({
-            let state = state.clone();
-            move || state.borrow_mut().decrement()
-        }),
-    ]
-}
-```
-
-## Runtime Panics
-
-`RefCell` panics if you violate borrowing rules at runtime:
-
-```rust
-let cell = RefCell::new(5);
-let borrow1 = cell.borrow();
-let borrow2 = cell.borrow_mut(); // PANIC: already borrowed
-```
-
-Use `try_borrow()` and `try_borrow_mut()` for fallible borrowing.
-
-## See Also
-
-- [own-rc-single-thread](./own-rc-single-thread.md) - Combining with Rc for shared ownership
-- [own-mutex-interior](./own-mutex-interior.md) - Thread-safe alternative

package/template/agent/skills/rust-developer/references/rust-rules/own-rwlock-readers.md

@@ -1,122 +0,0 @@
-# own-rwlock-readers
-
-> Use `RwLock<T>` when reads significantly outnumber writes
-
-## Why It Matters
-
-`Mutex<T>` allows only one thread to access data at a time, even for reads. `RwLock<T>` allows multiple concurrent readers OR one exclusive writer. For read-heavy workloads, this dramatically improves throughput by eliminating unnecessary serialization of read operations.
-
-## Bad
-
-```rust
-use std::sync::{Arc, Mutex};
-
-// Configuration rarely changes but is read constantly
-let config = Arc::new(Mutex::new(Config::load()));
-
-// Every read blocks other reads unnecessarily
-fn get_setting(config: &Mutex<Config>, key: &str) -> String {
-    let guard = config.lock().unwrap();
-    guard.get(key).to_string()
-}
-
-// 100 threads reading = serialized, one at a time
-```
-
-## Good
-
-```rust
-use std::sync::{Arc, RwLock};
-
-// Multiple readers can proceed concurrently
-let config = Arc::new(RwLock::new(Config::load()));
-
-fn get_setting(config: &RwLock<Config>, key: &str) -> String {
-    let guard = config.read().unwrap(); // Multiple threads can hold read lock
-    guard.get(key).to_string()
-}
-
-fn update_setting(config: &RwLock<Config>, key: &str, value: &str) {
-    let mut guard = config.write().unwrap(); // Exclusive access for writes
-    guard.set(key, value);
-}
-
-// 100 threads reading = parallel execution
-```
-
-## parking_lot::RwLock
-
-Prefer `parking_lot::RwLock` for better performance:
-
-```rust
-use parking_lot::RwLock;
-use std::sync::Arc;
-
-let data = Arc::new(RwLock::new(HashMap::new()));
-
-// Read - no unwrap needed
-let value = data.read().get("key").cloned();
-
-// Write
-data.write().insert("key".to_string(), "value".to_string());
-
-// Upgradeable read lock (unique to parking_lot)
-let upgradeable = data.upgradable_read();
-if upgradeable.get("key").is_none() {
-    let mut write = parking_lot::RwLockUpgradableReadGuard::upgrade(upgradeable);
-    write.insert("key".to_string(), "default".to_string());
-}
-```
-
-## When RwLock Hurts
-
-RwLock has overhead for tracking readers. It can be slower than Mutex when:
-
-| Scenario | Better Choice |
-|----------|---------------|
-| Writes are frequent (>20% of operations) | `Mutex` |
-| Lock held very briefly | `Mutex` |
-| Single-threaded | `RefCell` |
-| Reads dominate, lock held longer | `RwLock` |
-
-## Write Starvation
-
-Standard `RwLock` may starve writers if readers are continuous. `parking_lot::RwLock` is fair by default.
-
-```rust
-// parking_lot is writer-fair, preventing starvation
-use parking_lot::RwLock;
-
-// Or use std with explicit fairness (nightly)
-// #![feature(rwlock_downgrade)]
-```
-
-## Real-World Pattern: Cached Computation
-
-```rust
-use parking_lot::RwLock;
-use std::sync::Arc;
-
-struct CachedData {
-    cache: RwLock<Option<ExpensiveResult>>,
-}
-
-impl CachedData {
-    fn get(&self) -> ExpensiveResult {
-        // Fast path: read lock
-        if let Some(cached) = self.cache.read().as_ref() {
-            return cached.clone();
-        }
-        
-        // Slow path: compute and cache
-        let result = compute_expensive();
-        *self.cache.write() = Some(result.clone());
-        result
-    }
-}
-```
-
-## See Also
-
-- [own-mutex-interior](./own-mutex-interior.md) - When writes are frequent
-- [async-no-lock-await](./async-no-lock-await.md) - RwLock in async contexts

package/template/agent/skills/rust-developer/references/rust-rules/own-slice-over-vec.md

@@ -1,119 +0,0 @@
-# own-slice-over-vec
-
-> Accept `&[T]` not `&Vec<T>`, `&str` not `&String`
-
-## Why It Matters
-
-Accepting `&[T]` instead of `&Vec<T>` makes your function more flexible - it can accept slices from arrays, vectors, or other sources. Similarly, `&str` accepts string slices from `String`, `&'static str`, or substrings.
-
-## Bad
-
-```rust
-// Overly restrictive - only accepts &Vec
-fn sum(numbers: &Vec<i32>) -> i32 {
-    numbers.iter().sum()
-}
-
-// Overly restrictive - only accepts &String
-fn greet(name: &String) {
-    println!("Hello, {}", name);
-}
-
-// Can't call with arrays or slices
-let arr = [1, 2, 3];
-// sum(&arr);  // ERROR: expected &Vec<i32>
-
-let literal = "world";
-// greet(&literal);  // ERROR: expected &String
-```
-
-## Good
-
-```rust
-// Flexible - accepts any slice-like thing
-fn sum(numbers: &[i32]) -> i32 {
-    numbers.iter().sum()
-}
-
-// Flexible - accepts any string-like thing
-fn greet(name: &str) {
-    println!("Hello, {}", name);
-}
-
-// Now all of these work:
-let vec = vec![1, 2, 3];
-let arr = [4, 5, 6];
-let slice = &vec[0..2];
-
-sum(&vec);    // Vec coerces to slice
-sum(&arr);    // Array coerces to slice
-sum(slice);   // Slice works directly
-
-let string = String::from("Alice");
-let literal = "Bob";
-
-greet(&string);  // String coerces to &str
-greet(literal);  // &str works directly
-```
-
-## The Deref Coercion Chain
-
-```rust
-// These coercions happen automatically:
-// Vec<T>  -> &[T]   (via Deref)
-// String  -> &str   (via Deref)
-// Box<T>  -> &T     (via Deref)
-// Arc<T>  -> &T     (via Deref)
-
-fn process(data: &[u8]) { /* ... */ }
-
-let vec: Vec<u8> = vec![1, 2, 3];
-let boxed: Box<[u8]> = vec.into_boxed_slice();
-let arc: Arc<[u8]> = Arc::from(&[1, 2, 3][..]);
-
-process(&vec);    // Works
-process(&boxed);  // Works
-process(&arc);    // Works
-```
-
-## Path Types Too
-
-```rust
-// Bad
-fn read_config(path: &PathBuf) -> Config { /* ... */ }
-
-// Good - accepts &Path, &PathBuf, &str, &String
-fn read_config(path: &Path) -> Config { /* ... */ }
-
-// Even better - accept anything path-like
-fn read_config(path: impl AsRef<Path>) -> Config {
-    let path = path.as_ref();
-    // ...
-}
-```
-
-## When to Accept Owned Types
-
-```rust
-// Accept owned when you need to store it
-struct Logger {
-    prefix: String,  // Needs to own the string
-}
-
-impl Logger {
-    // Take ownership - caller decides to clone or move
-    fn new(prefix: String) -> Self {
-        Self { prefix }
-    }
-    
-    // Or use Into for flexibility
-    fn with_prefix(prefix: impl Into<String>) -> Self {
-        Self { prefix: prefix.into() }
-    }
-}
-```
-
-## See Also
-
-- [api-impl-asref](api-impl-asref.md) - Accept `impl AsRef<T>` for maximum flexibility
-- [own-borrow-over-clone](own-borrow-over-clone.md) - Prefer borrowing over cloning

package/template/agent/skills/rust-developer/references/rust-rules/perf-black-box-bench.md

@@ -1,153 +0,0 @@
-# perf-black-box-bench
-
-> Use black_box in benchmarks
-
-## Why It Matters
-
-The compiler aggressively optimizes code, potentially eliminating computations whose results aren't used. In benchmarks, this can lead to measuring nothing instead of the actual code. `std::hint::black_box()` prevents the compiler from optimizing away values, ensuring accurate measurements.
-
-## Bad
-
-```rust
-use criterion::{black_box, criterion_group, criterion_main, Criterion};
-
-fn benchmark_bad(c: &mut Criterion) {
-    c.bench_function("compute", |b| {
-        b.iter(|| {
-            let result = expensive_computation(42);
-            // Result unused - compiler may eliminate the call!
-        });
-    });
-}
-
-fn benchmark_also_bad(c: &mut Criterion) {
-    let input = 42;  // Constant - compiler may precompute
-    
-    c.bench_function("compute", |b| {
-        b.iter(|| {
-            expensive_computation(input)
-            // Return value may still be optimized away
-        });
-    });
-}
-```
-
-## Good
-
-```rust
-use criterion::{black_box, criterion_group, criterion_main, Criterion};
-
-fn benchmark_good(c: &mut Criterion) {
-    c.bench_function("compute", |b| {
-        b.iter(|| {
-            // black_box on input prevents constant folding
-            let result = expensive_computation(black_box(42));
-            // black_box on output prevents dead code elimination
-            black_box(result)
-        });
-    });
-}
-
-// Or simpler with Criterion's built-in support
-fn benchmark_simpler(c: &mut Criterion) {
-    c.bench_function("compute", |b| {
-        b.iter(|| expensive_computation(black_box(42)))
-    });
-}
-```
-
-## What black_box Does
-
-| Without black_box | With black_box |
-|-------------------|----------------|
-| Input may be constant-folded | Input treated as unknown |
-| Result may be eliminated | Result must be computed |
-| Loops may be optimized away | Each iteration runs |
-| Functions may be inlined | Call semantics preserved |
-
-## Standard Library Usage
-
-```rust
-use std::hint::black_box;
-
-fn main() {
-    // In std since Rust 1.66
-    let result = black_box(compute_something(black_box(input)));
-}
-```
-
-## Criterion's black_box
-
-Criterion re-exports `std::hint::black_box`:
-
-```rust
-use criterion::black_box;
-
-// Equivalent to std::hint::black_box
-```
-
-## Pattern: Benchmark with Setup
-
-```rust
-fn benchmark_with_setup(c: &mut Criterion) {
-    c.bench_function("process_data", |b| {
-        // Setup outside iter - not measured
-        let data = generate_test_data(1000);
-        
-        b.iter(|| {
-            // black_box the input reference
-            let result = process(black_box(&data));
-            black_box(result)
-        });
-    });
-}
-```
-
-## Pattern: Benchmark Multiple Inputs
-
-```rust
-fn benchmark_sizes(c: &mut Criterion) {
-    let mut group = c.benchmark_group("scaling");
-    
-    for size in [100, 1000, 10000] {
-        let data = generate_data(size);
-        
-        group.bench_with_input(
-            BenchmarkId::from_parameter(size),
-            &data,
-            |b, data| {
-                b.iter(|| process(black_box(data)))
-            },
-        );
-    }
-    group.finish();
-}
-```
-
-## Common Mistakes
-
-```rust
-// WRONG: black_box inside loop does nothing useful
-for _ in 0..1000 {
-    black_box(());  // Doesn't help
-    compute();
-}
-
-// RIGHT: black_box the computation result
-for _ in 0..1000 {
-    black_box(compute());
-}
-
-// WRONG: Only blocking output, not input
-let x = 42;  // Constant, may be optimized
-black_box(expensive(x));
-
-// RIGHT: Block both
-black_box(expensive(black_box(42)));
-```
-
-## See Also
-
-- [test-criterion-bench](./test-criterion-bench.md) - Using Criterion
-- [perf-profile-first](./perf-profile-first.md) - Profile before optimize
-- [perf-release-profile](./perf-release-profile.md) - Release settings