agy-superpowers 5.2.2 → 5.2.4

package/template/agent/skills/rust-developer/references/rust-rules/anti-lock-across-await.md

@@ -1,127 +0,0 @@
-# anti-lock-across-await
-
-> Don't hold locks across await points
-
-## Why It Matters
-
-Holding a `Mutex` or `RwLock` guard across an `.await` causes the lock to be held while the task is suspended. Other tasks waiting for the lock block indefinitely. With `std::sync::Mutex`, this is even worse—it can deadlock the entire runtime.
-
-## Bad
-
-```rust
-use std::sync::Mutex;
-use tokio::sync::Mutex as AsyncMutex;
-
-// DEADLOCK RISK: std::sync::Mutex held across await
-async fn bad_std_mutex(data: &Mutex<Vec<i32>>) {
-    let mut guard = data.lock().unwrap();
-    do_async_work().await;  // Lock held during await!
-    guard.push(42);
-}
-
-// BLOCKS OTHER TASKS: tokio Mutex held across await
-async fn bad_async_mutex(data: &AsyncMutex<Vec<i32>>) {
-    let mut guard = data.lock().await;
-    slow_network_call().await;  // Lock held for entire call!
-    guard.push(42);
-}
-```
-
-## Good
-
-```rust
-use std::sync::Mutex;
-use tokio::sync::Mutex as AsyncMutex;
-
-// Release lock before await
-async fn good_approach(data: &Mutex<Vec<i32>>) {
-    let value = {
-        let guard = data.lock().unwrap();
-        guard.last().copied()  // Extract what you need
-    };  // Lock released here
-    
-    let result = do_async_work(value).await;
-    
-    {
-        let mut guard = data.lock().unwrap();
-        guard.push(result);
-    }
-}
-
-// Minimize lock scope with async mutex
-async fn good_async_mutex(data: &AsyncMutex<Vec<i32>>, item: i32) {
-    // Quick lock, quick release
-    data.lock().await.push(item);
-    
-    // Async work without lock
-    let result = slow_network_call().await;
-    
-    // Quick lock again
-    data.lock().await.push(result);
-}
-```
-
-## Pattern: Clone Before Await
-
-```rust
-async fn process(data: &AsyncMutex<Config>) -> Result<()> {
-    // Clone inside lock scope
-    let config = data.lock().await.clone();
-    
-    // Now use config freely across awaits
-    let result = fetch_data(&config.url).await?;
-    process_result(&config, result).await?;
-    
-    Ok(())
-}
-```
-
-## Pattern: Restructure to Avoid Lock
-
-```rust
-// Instead of locking a shared map
-struct Service {
-    data: AsyncMutex<HashMap<String, Data>>,
-}
-
-// Use channels or owned data
-struct BetterService {
-    // Each task owns its data via channels
-    sender: mpsc::Sender<Request>,
-}
-
-impl BetterService {
-    async fn request(&self, key: String) -> Data {
-        let (tx, rx) = oneshot::channel();
-        self.sender.send(Request { key, respond: tx }).await?;
-        rx.await?
-    }
-}
-```
-
-## What Can Cross Await
-
-| Type | Safe Across Await? |
-|------|--------------------|
-| `std::sync::Mutex` guard | **NO** - can deadlock |
-| `std::sync::RwLock` guard | **NO** - can deadlock |
-| `tokio::sync::Mutex` guard | Allowed but blocks tasks |
-| `tokio::sync::RwLock` guard | Allowed but blocks tasks |
-| Owned values | Yes |
-| `Arc<T>` | Yes |
-| References | Depends on lifetime |
-
-## Detection
-
-```toml
-# Cargo.toml
-[lints.clippy]
-await_holding_lock = "deny"
-await_holding_refcell_ref = "deny"
-```
-
-## See Also
-
-- [async-no-lock-await](./async-no-lock-await.md) - Async lock patterns
-- [async-clone-before-await](./async-clone-before-await.md) - Clone pattern
-- [own-mutex-interior](./own-mutex-interior.md) - Mutex usage

package/template/agent/skills/rust-developer/references/rust-rules/anti-over-abstraction.md

@@ -1,120 +0,0 @@
-# anti-over-abstraction
-
-> Don't over-abstract with excessive generics
-
-## Why It Matters
-
-Generics and traits are powerful but come at a cost: compile times, binary size, and cognitive load. Over-abstraction—making everything generic "for flexibility"—often adds complexity without benefit. Start concrete; generalize when you have real use cases.
-
-## Bad
-
-```rust
-// Overly generic for a simple function
-fn add<T, U, R>(a: T, b: U) -> R
-where
-    T: Into<R>,
-    U: Into<R>,
-    R: std::ops::Add<Output = R>,
-{
-    a.into() + b.into()
-}
-
-// Just call add(1, 2) - why make it this complex?
-
-// Trait explosion
-trait Readable {}
-trait Writable {}
-trait ReadWritable: Readable + Writable {}
-trait AsyncReadable {}
-trait AsyncWritable {}
-trait AsyncReadWritable: AsyncReadable + AsyncWritable {}
-
-// Abstract factory pattern (Java flashback)
-trait Factory<T> {
-    fn create(&self) -> T;
-}
-trait FactoryFactory<F: Factory<T>, T> {
-    fn create_factory(&self) -> F;
-}
-```
-
-## Good
-
-```rust
-// Concrete implementation - clear and simple
-fn add_i32(a: i32, b: i32) -> i32 {
-    a + b
-}
-
-// Generic when actually needed (e.g., library code)
-fn add<T: std::ops::Add<Output = T>>(a: T, b: T) -> T {
-    a + b
-}
-
-// Simple traits for actual polymorphism needs
-trait Storage {
-    fn save(&self, key: &str, value: &[u8]) -> Result<(), Error>;
-    fn load(&self, key: &str) -> Result<Vec<u8>, Error>;
-}
-
-// Concrete types first
-struct FileStorage { path: PathBuf }
-struct MemoryStorage { data: HashMap<String, Vec<u8>> }
-```
-
-## Signs of Over-Abstraction
-
-| Sign | Symptom |
-|------|---------|
-| Single implementation | Generic trait with only one impl |
-| Type parameter soup | `T, U, V, W` everywhere |
-| Marker traits | Traits with no methods |
-| Deep trait bounds | `where T: A + B + C + D + E` |
-| Phantom generics | Type parameters not used meaningfully |
-
-## When to Generalize
-
-Generalize when:
-- You have 2+ concrete types that share behavior
-- You're writing library code for public consumption
-- Performance requires static dispatch
-- The abstraction simplifies the API
-
-Don't generalize when:
-- You "might need it later" (YAGNI)
-- Only one type will ever implement it
-- It makes code harder to understand
-
-## Rule of Three
-
-Wait until you have three similar concrete implementations before abstracting:
-
-```rust
-// Version 1: Just FileStorage
-struct FileStorage { /* ... */ }
-
-// Version 2: Added MemoryStorage, similar interface
-struct MemoryStorage { /* ... */ }
-
-// Version 3: Now Redis too - time to abstract
-trait Storage {
-    fn save(&self, key: &str, value: &[u8]) -> Result<()>;
-    fn load(&self, key: &str) -> Result<Vec<u8>>;
-}
-```
-
-## Prefer Concrete Types in Private Code
-
-```rust
-// Internal function - concrete type is fine
-fn process_orders(db: &PostgresDb, orders: Vec<Order>) { }
-
-// Public API - might benefit from abstraction
-pub fn process_orders<S: Storage>(storage: &S, orders: Vec<Order>) { }
-```
-
-## See Also
-
-- [type-generic-bounds](./type-generic-bounds.md) - Minimal bounds
-- [api-sealed-trait](./api-sealed-trait.md) - Controlled extension
-- [anti-type-erasure](./anti-type-erasure.md) - When Box<dyn> is wrong

package/template/agent/skills/rust-developer/references/rust-rules/anti-panic-expected.md

@@ -1,131 +0,0 @@
-# anti-panic-expected
-
-> Don't panic on expected or recoverable errors
-
-## Why It Matters
-
-Panics crash the program. They're for unrecoverable situations—bugs, corrupted state, invariant violations. Using panic for expected conditions (network failures, file not found, invalid input) makes programs fragile and forces callers to catch panics or die.
-
-Use `Result` for recoverable errors.
-
-## Bad
-
-```rust
-// Network failures are expected
-fn fetch_data(url: &str) -> Data {
-    let response = reqwest::blocking::get(url)
-        .expect("network error");  // Crashes on timeout
-    response.json().expect("invalid json")  // Crashes on bad response
-}
-
-// User input is often invalid
-fn parse_config(input: &str) -> Config {
-    toml::from_str(input).expect("invalid config")  // Crashes on typo
-}
-
-// Files may not exist
-fn load_settings() -> Settings {
-    let content = fs::read_to_string("settings.json")
-        .expect("settings not found");  // Crashes if missing
-    serde_json::from_str(&content).expect("invalid settings")
-}
-
-// Custom panic for validation
-fn process_age(age: i32) {
-    if age < 0 {
-        panic!("age cannot be negative");  // Should return error
-    }
-}
-```
-
-## Good
-
-```rust
-// Return errors for expected failures
-fn fetch_data(url: &str) -> Result<Data, FetchError> {
-    let response = reqwest::blocking::get(url)
-        .context("failed to connect")?;
-    let data = response.json()
-        .context("failed to parse response")?;
-    Ok(data)
-}
-
-// Validate and return Result
-fn parse_config(input: &str) -> Result<Config, ConfigError> {
-    toml::from_str(input).map_err(ConfigError::Parse)
-}
-
-// Handle missing files gracefully
-fn load_settings() -> Result<Settings, SettingsError> {
-    let content = fs::read_to_string("settings.json")?;
-    let settings = serde_json::from_str(&content)?;
-    Ok(settings)
-}
-
-// Return error for validation failure
-fn process_age(age: i32) -> Result<(), ValidationError> {
-    if age < 0 {
-        return Err(ValidationError::NegativeAge);
-    }
-    Ok(())
-}
-```
-
-## When to Panic
-
-Panic IS appropriate for:
-
-```rust
-// Bug detection - invariant violated
-fn get_unchecked(&self, index: usize) -> &T {
-    assert!(index < self.len(), "index out of bounds - this is a bug");
-    unsafe { self.data.get_unchecked(index) }
-}
-
-// Unrecoverable state
-fn init() {
-    if !CAN_PROCEED {
-        panic!("system requirements not met");
-    }
-}
-
-// Tests
-#[test]
-fn test_fails() {
-    panic!("expected panic in test");
-}
-```
-
-## Decision Guide
-
-| Condition | Action |
-|-----------|--------|
-| Invalid user input | Return `Err` |
-| Network failure | Return `Err` |
-| File not found | Return `Err` |
-| Malformed data | Return `Err` |
-| Bug/impossible state | `panic!` or `unreachable!` |
-| Failed assertion in test | `panic!` |
-| Unrecoverable init failure | `panic!` |
-
-## Anti-pattern: panic! for Control Flow
-
-```rust
-// BAD: Using panic for control flow
-fn find_or_die(items: &[Item], id: u64) -> &Item {
-    items.iter()
-        .find(|i| i.id == id)
-        .unwrap_or_else(|| panic!("item {} not found", id))
-}
-
-// GOOD: Return Option or Result
-fn find(items: &[Item], id: u64) -> Option<&Item> {
-    items.iter().find(|i| i.id == id)
-}
-```
-
-## See Also
-
-- [err-result-over-panic](./err-result-over-panic.md) - Use Result
-- [anti-unwrap-abuse](./anti-unwrap-abuse.md) - Unwrap anti-pattern
-- [err-expect-bugs-only](./err-expect-bugs-only.md) - When to expect

package/template/agent/skills/rust-developer/references/rust-rules/anti-premature-optimize.md

@@ -1,156 +0,0 @@
-# anti-premature-optimize
-
-> Don't optimize before profiling
-
-## Why It Matters
-
-Premature optimization wastes time, complicates code, and often targets the wrong bottlenecks. Most code isn't performance-critical; the hot 10% matters. Profile first, then optimize the actual bottlenecks with data-driven decisions.
-
-## Bad
-
-```rust
-// "Optimizing" without measurement
-fn sum(data: &[i32]) -> i32 {
-    // Using unsafe "for performance" without profiling
-    unsafe {
-        let mut sum = 0;
-        for i in 0..data.len() {
-            sum += *data.get_unchecked(i);
-        }
-        sum
-    }
-}
-
-// Complex caching with no evidence it's needed
-lazy_static! {
-    static ref CACHE: RwLock<HashMap<String, Arc<Result>>> = 
-        RwLock::new(HashMap::new());
-}
-
-// Hand-rolled data structures "for speed"
-struct MyVec<T> {
-    ptr: *mut T,
-    len: usize,
-    cap: usize,
-}
-```
-
-## Good
-
-```rust
-// Simple, idiomatic - let compiler optimize
-fn sum(data: &[i32]) -> i32 {
-    data.iter().sum()
-}
-
-// Profile, then optimize if needed
-fn sum_optimized(data: &[i32]) -> i32 {
-    // After profiling showed this is a bottleneck,
-    // we measured that manual SIMD gives 3x speedup
-    #[cfg(target_arch = "x86_64")]
-    {
-        // SIMD implementation with benchmark data
-    }
-    #[cfg(not(target_arch = "x86_64"))]
-    {
-        data.iter().sum()
-    }
-}
-
-// Use standard library - it's well-optimized
-let cache: HashMap<String, Result> = HashMap::new();
-```
-
-## Profiling Workflow
-
-```bash
-# 1. Write correct code first
-cargo build --release
-
-# 2. Profile with real workloads
-cargo flamegraph --bin my_app -- --real-args
-# or
-cargo bench
-
-# 3. Identify hotspots (top 10% of time)
-
-# 4. Measure before optimizing
-# 5. Optimize ONE thing
-# 6. Measure after - verify improvement
-# 7. Repeat if still slow
-```
-
-## Optimization Principles
-
-| Do | Don't |
-|----|-------|
-| Profile first | Guess at bottlenecks |
-| Optimize hotspots | Optimize everything |
-| Measure improvement | Assume it's faster |
-| Keep it simple | Add complexity speculatively |
-| Trust the compiler | Outsmart the compiler |
-
-## When to Optimize
-
-```rust
-// AFTER profiling shows this is 40% of runtime
-#[inline]
-fn hot_function(data: &[u8]) -> u64 {
-    // Optimized implementation justified by benchmarks
-}
-
-// Clear, measurable benefit documented
-/// Pre-allocated buffer for repeated formatting.
-/// Benchmarks show 3x speedup for >1000 calls/sec workloads.
-struct FormatterPool {
-    buffers: Vec<String>,
-}
-```
-
-## Common Premature Optimizations
-
-| Premature | Reality |
-|-----------|---------|
-| `#[inline(always)]` everywhere | Compiler usually knows better |
-| `unsafe` for bounds check removal | Iterator does this safely |
-| Custom allocator | Default is usually fine |
-| Object pooling | Allocator is fast enough |
-| Manual SIMD | Auto-vectorization works |
-
-## Profile Tools
-
-```bash
-# Sampling profiler
-perf record ./target/release/app && perf report
-
-# Flamegraph
-cargo install flamegraph
-cargo flamegraph
-
-# Criterion benchmarks
-cargo bench
-
-# Memory profiling
-valgrind --tool=massif ./target/release/app
-```
-
-## Document Optimizations
-
-```rust
-/// Lookup table for fast character classification.
-/// 
-/// # Performance
-/// 
-/// Benchmarked with criterion (benchmarks/char_class.rs):
-/// - Table lookup: 2.3ns/op
-/// - Match statement: 8.7ns/op
-/// 
-/// Justified for hot path in parser (called 10M+ times).
-static CHAR_CLASS: [CharClass; 256] = [/* ... */];
-```
-
-## See Also
-
-- [perf-profile-first](./perf-profile-first.md) - Profile before optimize
-- [test-criterion-bench](./test-criterion-bench.md) - Benchmarking
-- [opt-inline-small](./opt-inline-small.md) - Inline guidelines

package/template/agent/skills/rust-developer/references/rust-rules/anti-string-for-str.md

@@ -1,122 +0,0 @@
-# anti-string-for-str
-
-> Don't accept &String when &str works
-
-## Why It Matters
-
-`&String` is strictly less flexible than `&str`. A `&str` can be created from `String`, `&str`, literals, and slices. A `&String` requires exactly a `String`. This forces callers to allocate when they might not need to.
-
-## Bad
-
-```rust
-// Forces callers to have a String
-fn greet(name: &String) {
-    println!("Hello, {}", name);
-}
-
-// Caller must allocate
-greet(&"Alice".to_string());  // Unnecessary allocation
-greet(&name);                 // Only works if name is String
-
-// In struct
-struct Config {
-    name: String,
-}
-
-impl Config {
-    fn set_name(&mut self, name: &String) {  // Too restrictive
-        self.name = name.clone();
-    }
-}
-```
-
-## Good
-
-```rust
-// Accept &str - works with String, &str, literals
-fn greet(name: &str) {
-    println!("Hello, {}", name);
-}
-
-// All these work
-greet("Alice");           // String literal
-greet(&name);             // &String coerces to &str
-greet(name.as_str());     // Explicit &str
-
-// In struct
-impl Config {
-    fn set_name(&mut self, name: &str) {
-        self.name = name.to_string();
-    }
-    
-    // Or accept owned String if caller usually has one
-    fn set_name_owned(&mut self, name: String) {
-        self.name = name;
-    }
-    
-    // Or be generic
-    fn set_name_into(&mut self, name: impl Into<String>) {
-        self.name = name.into();
-    }
-}
-```
-
-## Deref Coercion
-
-`String` implements `Deref<Target = str>`, so `&String` automatically coerces to `&str`:
-
-```rust
-fn takes_str(s: &str) { }
-
-let owned = String::from("hello");
-takes_str(&owned);  // &String -> &str via Deref
-```
-
-## When to Accept &String
-
-Rarely. Maybe if you need `String`-specific methods:
-
-```rust
-fn needs_capacity(s: &String) -> usize {
-    s.capacity()  // Only String has capacity()
-}
-```
-
-But usually you'd take `&str` and let the caller manage the `String`.
-
-## Pattern: Flexible APIs
-
-```rust
-// Most flexible: accept anything that can become &str
-fn process(input: impl AsRef<str>) {
-    let s: &str = input.as_ref();
-    // ...
-}
-
-process("literal");
-process(String::from("owned"));
-process(&some_string);
-```
-
-## Similar Anti-patterns
-
-| Anti-pattern | Better |
-|--------------|--------|
-| `&String` | `&str` |
-| `&Vec<T>` | `&[T]` |
-| `&Box<T>` | `&T` |
-| `&PathBuf` | `&Path` |
-| `&OsString` | `&OsStr` |
-
-## Clippy Detection
-
-```toml
-[lints.clippy]
-ptr_arg = "warn"  # Catches &String, &Vec, &PathBuf
-```
-
-## See Also
-
-- [anti-vec-for-slice](./anti-vec-for-slice.md) - Similar pattern for Vec
-- [own-slice-over-vec](./own-slice-over-vec.md) - Slice patterns
-- [api-impl-asref](./api-impl-asref.md) - AsRef pattern