agy-superpowers 5.2.2 → 5.2.4

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

package/template/agent/skills/rust-developer/references/rust-rules/perf-chain-avoid.md

@@ -1,136 +0,0 @@
-# perf-chain-avoid
-
-> Avoid chain in hot loops
-
-## Why It Matters
-
-`Iterator::chain()` adds overhead for checking which iterator is active on every `.next()` call. In hot loops, this branch prediction overhead can impact performance. For performance-critical code, prefer single iterators or pre-combined collections.
-
-## Bad
-
-```rust
-// Chain in hot inner loop
-fn process_hot_path(a: &[i32], b: &[i32]) -> i64 {
-    let mut sum = 0i64;
-    
-    // Called millions of times
-    for _ in 0..1_000_000 {
-        for x in a.iter().chain(b.iter()) {  // Branch every iteration
-            sum += *x as i64;
-        }
-    }
-    sum
-}
-
-// Chaining multiple small slices in tight loop
-fn combine_results(parts: &[&[u8]]) -> Vec<u8> {
-    let mut result = Vec::new();
-    for part in parts {
-        for byte in std::iter::once(&0u8).chain(part.iter()) {
-            result.push(*byte);
-        }
-    }
-    result
-}
-```
-
-## Good
-
-```rust
-// Separate loops - branch-free inner loops
-fn process_hot_path(a: &[i32], b: &[i32]) -> i64 {
-    let mut sum = 0i64;
-    
-    for _ in 0..1_000_000 {
-        for x in a {
-            sum += *x as i64;
-        }
-        for x in b {
-            sum += *x as i64;
-        }
-    }
-    sum
-}
-
-// Pre-combine outside hot loop
-fn combine_results(parts: &[&[u8]]) -> Vec<u8> {
-    let mut result = Vec::new();
-    for part in parts {
-        result.push(0u8);
-        result.extend_from_slice(part);
-    }
-    result
-}
-```
-
-## When Chain Is Fine
-
-Chain is perfectly acceptable when:
-
-```rust
-// One-time iteration, not in hot path
-fn collect_all(a: Vec<i32>, b: Vec<i32>) -> Vec<i32> {
-    a.into_iter().chain(b).collect()
-}
-
-// Lazy evaluation with short-circuit
-fn find_in_either(a: &[Item], b: &[Item], target: i32) -> Option<&Item> {
-    a.iter().chain(b.iter()).find(|x| x.id == target)
-}
-
-// Small number of elements
-fn get_prefixes() -> impl Iterator<Item = &'static str> {
-    ["Mr.", "Mrs.", "Dr."].iter().copied()
-        .chain(["Prof."].iter().copied())
-}
-```
-
-## Alternative Patterns
-
-### Pre-allocate and Extend
-
-```rust
-fn merge_slices(slices: &[&[i32]]) -> Vec<i32> {
-    let total: usize = slices.iter().map(|s| s.len()).sum();
-    let mut result = Vec::with_capacity(total);
-    for slice in slices {
-        result.extend_from_slice(slice);
-    }
-    result
-}
-```
-
-### Use append for Vecs
-
-```rust
-fn combine_vecs(mut a: Vec<i32>, mut b: Vec<i32>) -> Vec<i32> {
-    a.append(&mut b);  // Moves elements, no reallocation if a has capacity
-    a
-}
-```
-
-### Flatten Instead of Chain
-
-```rust
-// Instead of: a.iter().chain(b.iter()).chain(c.iter())
-let all = [a, b, c];
-for item in all.iter().flat_map(|slice| slice.iter()) {
-    process(item);
-}
-```
-
-## Performance Impact
-
-| Pattern | Per-Item Overhead |
-|---------|-------------------|
-| Single iterator | None |
-| `chain(a, b)` | 1 branch per item |
-| `chain(a, b, c)` | 2 branches per item |
-| Nested chains | Compounds |
-| Separate loops | None (but code duplication) |
-
-## See Also
-
-- [perf-iter-over-index](./perf-iter-over-index.md) - Prefer iterators
-- [perf-extend-batch](./perf-extend-batch.md) - Batch insertions
-- [opt-cache-friendly](./opt-cache-friendly.md) - Cache-friendly patterns