agy-superpowers 5.1.4 → 5.1.5

package/template/agent/skills/rust-developer/references/rust-rules/opt-codegen-units.md

@@ -0,0 +1,142 @@
+# opt-codegen-units
+
+> Set `codegen-units = 1` for maximum optimization in release builds
+
+## Why It Matters
+
+By default, Cargo splits code into multiple codegen units for parallel compilation. This speeds up builds but prevents some cross-unit optimizations. Setting `codegen-units = 1` allows LLVM to optimize across the entire crate, potentially improving runtime performance by 5-20% at the cost of slower builds.
+
+## Bad
+
+```toml
+# Cargo.toml - default settings
+[profile.release]
+# codegen-units defaults to 16
+# Fast to compile, but misses optimization opportunities
+```
+
+## Good
+
+```toml
+# Cargo.toml - optimized for runtime performance
+[profile.release]
+codegen-units = 1  # Single unit = better optimization
+lto = true         # Link-time optimization
+opt-level = 3      # Maximum optimization
+```
+
+## What codegen-units Affects
+
+| Codegen Units | Compile Time | Runtime Performance | Memory Use |
+|---------------|--------------|---------------------|------------|
+| 16 (default)  | Faster       | Baseline            | Lower      |
+| 4-8           | Moderate     | Slightly better     | Moderate   |
+| 1             | Slower       | Best                | Higher     |
+
+## How It Works
+
+```rust
+// With codegen-units = 16:
+// - Crate split into 16 independent compilation units
+// - Compiled in parallel
+// - Limited visibility between units for optimization
+
+// With codegen-units = 1:
+// - Entire crate in single unit
+// - LLVM sees all code at once
+// - Can inline across module boundaries
+// - Better dead code elimination
+// - Better constant propagation
+```
+
+## Full Release Profile
+
+```toml
+[profile.release]
+# Maximum runtime performance
+opt-level = 3
+lto = "fat"
+codegen-units = 1
+panic = "abort"      # Smaller binary, slight perf gain
+strip = true         # Smaller binary
+
+[profile.release-with-debug]
+# Performance with debugging ability
+inherits = "release"
+debug = true         # Keep debug symbols
+strip = false
+
+[profile.bench]
+# For benchmarking
+inherits = "release"
+```
+
+## Build Time Trade-offs
+
+```bash
+# Default release build (fast compile)
+cargo build --release
+# Time: ~30s
+
+# Optimized release build (slow compile, fast runtime)
+# With codegen-units = 1, lto = "fat"
+cargo build --release
+# Time: ~2-5min, but potentially 10-20% faster binary
+```
+
+## Per-Profile Configuration
+
+```toml
+# Fast debug builds
+[profile.dev]
+codegen-units = 256  # Maximum parallelism
+
+# Fast CI builds
+[profile.ci]
+inherits = "release"
+codegen-units = 16   # Balance compile time vs runtime
+lto = "thin"         # Faster than "fat"
+
+# Production release
+[profile.production]
+inherits = "release"
+codegen-units = 1
+lto = "fat"
+```
+
+## When to Use What
+
+```rust
+// codegen-units = 16 (default)
+// - Development builds
+// - CI where compile time matters
+// - When runtime performance isn't critical
+
+// codegen-units = 1
+// - Production deployments
+// - Performance-critical applications
+// - Final releases
+// - Benchmarking
+```
+
+## Measuring Impact
+
+```bash
+# Build with different settings
+cargo build --release
+
+# Benchmark
+cargo bench
+
+# Compare binary sizes
+ls -lh target/release/my_binary
+
+# Profile runtime
+perf stat ./target/release/my_binary
+```
+
+## See Also
+
+- [opt-lto-release](./opt-lto-release.md) - Link-time optimization
+- [opt-pgo-profile](./opt-pgo-profile.md) - Profile-guided optimization
+- [opt-target-cpu](./opt-target-cpu.md) - CPU-specific optimization

package/template/agent/skills/rust-developer/references/rust-rules/opt-cold-unlikely.md

@@ -0,0 +1,152 @@
+# opt-cold-unlikely
+
+> Mark unlikely code paths with `#[cold]` to help compiler optimization
+
+## Why It Matters
+
+The `#[cold]` attribute tells the compiler that a function is rarely called. The compiler uses this to optimize code layout—keeping cold code away from hot code improves instruction cache utilization. Combined with branch layout optimization, this can measurably improve performance.
+
+## Bad
+
+```rust
+// All branches treated equally
+fn validate(input: &str) -> Result<Data, ValidationError> {
+    if input.is_empty() {
+        return Err(ValidationError::Empty);  // Rare
+    }
+    
+    if input.len() > 1000 {
+        return Err(ValidationError::TooLong);  // Rare  
+    }
+    
+    if !input.is_ascii() {
+        return Err(ValidationError::NonAscii);  // Rare
+    }
+    
+    // This is the common case
+    Ok(parse_data(input))
+}
+```
+
+## Good
+
+```rust
+fn validate(input: &str) -> Result<Data, ValidationError> {
+    if input.is_empty() {
+        return cold_empty_error();
+    }
+    
+    if input.len() > 1000 {
+        return cold_too_long_error();
+    }
+    
+    if !input.is_ascii() {
+        return cold_non_ascii_error();
+    }
+    
+    Ok(parse_data(input))
+}
+
+#[cold]
+fn cold_empty_error() -> Result<Data, ValidationError> {
+    Err(ValidationError::Empty)
+}
+
+#[cold]
+fn cold_too_long_error() -> Result<Data, ValidationError> {
+    Err(ValidationError::TooLong)
+}
+
+#[cold]
+fn cold_non_ascii_error() -> Result<Data, ValidationError> {
+    Err(ValidationError::NonAscii)
+}
+```
+
+## What #[cold] Does
+
+1. **Code placement**: Cold functions are placed in separate code sections, away from hot code
+2. **Branch prediction**: Compiler generates branch hints favoring the non-cold path
+3. **Inlining decisions**: Cold functions are not inlined into hot paths
+4. **Optimization budget**: Compiler spends less effort optimizing cold code
+
+## Common Cold Patterns
+
+```rust
+// Error handling
+#[cold]
+fn handle_error<E: std::fmt::Display>(e: E) -> ! {
+    eprintln!("Fatal error: {}", e);
+    std::process::exit(1);
+}
+
+// Logging rare events
+#[cold]
+fn log_rare_event(event: &Event) {
+    log::warn!("Rare event occurred: {:?}", event);
+}
+
+// Fallback paths
+#[cold]
+fn slow_fallback(data: &Data) -> Output {
+    // This path should rarely be taken
+    compute_slowly(data)
+}
+
+// Panic handlers
+#[cold]
+fn panic_invalid_state(state: &State) -> ! {
+    panic!("Invalid state: {:?}", state);
+}
+```
+
+## Assertions and Invariants
+
+```rust
+fn get_unchecked(&self, index: usize) -> &T {
+    if index >= self.len {
+        cold_bounds_panic(index, self.len);
+    }
+    unsafe { &*self.ptr.add(index) }
+}
+
+#[cold]
+#[inline(never)]
+fn cold_bounds_panic(index: usize, len: usize) -> ! {
+    panic!("index out of bounds: the len is {} but the index is {}", len, index);
+}
+```
+
+## Combining with #[inline(never)]
+
+```rust
+// Usually combine both for maximum effect
+#[cold]
+#[inline(never)]
+fn error_path() -> Error {
+    // Complex error construction stays out of hot code
+    Error {
+        backtrace: Backtrace::capture(),
+        context: gather_context(),
+    }
+}
+```
+
+## Measuring Impact
+
+```rust
+// Check code layout with objdump
+// objdump -d target/release/binary | less
+
+// Look for .cold sections
+// nm target/release/binary | grep cold
+
+// Profile to verify improvement
+// perf stat -e cache-misses,cache-references ./binary
+```
+
+## See Also
+
+- [opt-inline-never-cold](./opt-inline-never-cold.md) - Combining with inline(never)
+- [opt-likely-hint](./opt-likely-hint.md) - Branch prediction hints
+- [err-result-over-panic](./err-result-over-panic.md) - Error handling

package/template/agent/skills/rust-developer/references/rust-rules/opt-inline-always-rare.md

@@ -0,0 +1,141 @@
+# opt-inline-always-rare
+
+> Use `#[inline(always)]` sparingly—only for critical hot paths proven by profiling
+
+## Why It Matters
+
+`#[inline(always)]` forces the compiler to inline a function regardless of heuristics. Overuse increases binary size, hurts instruction cache, and can slow down code. The compiler is usually smarter about inlining than humans. Reserve this for measured hot paths where benchmarks prove a benefit.
+
+## Bad
+
+```rust
+// Annotating everything - trusting intuition over data
+#[inline(always)]
+pub fn get_name(&self) -> &str {
+    &self.name
+}
+
+#[inline(always)]
+pub fn calculate_tax(amount: f64) -> f64 {
+    amount * 0.1
+}
+
+#[inline(always)]
+fn helper(x: i32) -> i32 {
+    x + 1
+}
+
+// Result: bloated binary, poor cache utilization
+```
+
+## Good
+
+```rust
+// Let compiler decide for most functions
+pub fn get_name(&self) -> &str {
+    &self.name
+}
+
+pub fn calculate_tax(amount: f64) -> f64 {
+    amount * 0.1
+}
+
+// Only force inline for proven hot paths
+impl Hasher for MyHasher {
+    // Hasher::write is called millions of times in tight loops
+    // Profiling showed 15% improvement from forced inlining
+    #[inline(always)]
+    fn write(&mut self, bytes: &[u8]) {
+        // Very small, very hot
+        self.state = self.state.wrapping_add(bytes.len() as u64);
+    }
+}
+```
+
+## When #[inline(always)] Helps
+
+```rust
+// ✅ Tiny functions in hot inner loops
+#[inline(always)]
+fn fast_hash(a: u64, b: u64) -> u64 {
+    a.wrapping_mul(b).wrapping_add(a)
+}
+
+// ✅ Generic functions that benefit from monomorphization
+#[inline(always)]
+fn swap<T>(a: &mut T, b: &mut T) {
+    std::mem::swap(a, b);
+}
+
+// ✅ Iterator adapters and closures
+#[inline(always)]
+fn apply<T, F: Fn(T) -> T>(f: F, x: T) -> T {
+    f(x)
+}
+
+// ✅ SIMD/vectorization helpers
+#[inline(always)]
+fn add_simd(a: &[f32], b: &[f32], out: &mut [f32]) {
+    // ...
+}
+```
+
+## Inline Variants
+
+```rust
+// #[inline] - hint to inline, compiler may ignore
+#[inline]
+fn suggested_inline(x: i32) -> i32 { x + 1 }
+
+// #[inline(always)] - force inline (almost always)
+#[inline(always)]
+fn force_inline(x: i32) -> i32 { x + 1 }
+
+// #[inline(never)] - prevent inlining (for profiling, code size)
+#[inline(never)]
+fn no_inline(x: i32) -> i32 { x + 1 }
+
+// No annotation - compiler decides based on heuristics
+fn compiler_decides(x: i32) -> i32 { x + 1 }
+```
+
+## Measuring Inline Impact
+
+```rust
+// Use criterion to benchmark
+use criterion::{criterion_group, criterion_main, Criterion};
+
+fn bench_with_inline(c: &mut Criterion) {
+    c.bench_function("hot_path_inline", |b| {
+        b.iter(|| hot_loop())
+    });
+}
+
+// Compare binary sizes
+// cargo bloat --release --crates
+
+// Check if function was inlined
+// cargo asm --rust my_crate::hot_function
+```
+
+## Generic Functions
+
+```rust
+// Generic functions across crate boundaries often need #[inline]
+// Because the generic code is compiled in the calling crate
+
+// In library crate:
+#[inline]  // Allow inlining in downstream crates
+pub fn generic_function<T: Display>(x: T) {
+    println!("{}", x);
+}
+
+// Without #[inline], the generic function can't be inlined
+// across crate boundaries even if beneficial
+```
+
+## See Also
+
+- [opt-inline-small](./opt-inline-small.md) - Regular inline for small functions
+- [opt-inline-never-cold](./opt-inline-never-cold.md) - Preventing inlining
+- [perf-profile-first](./perf-profile-first.md) - Profile before optimizing

package/template/agent/skills/rust-developer/references/rust-rules/opt-inline-never-cold.md

@@ -0,0 +1,181 @@
+# opt-inline-never-cold
+
+> Use `#[inline(never)]` and `#[cold]` for error paths and rarely-executed code
+
+## Why It Matters
+
+Inlining error handling code into hot paths wastes instruction cache space and can prevent other optimizations. `#[inline(never)]` keeps cold code out of the hot path. `#[cold]` tells the compiler this branch is unlikely, enabling better branch prediction hints and code layout.
+
+## Bad
+
+```rust
+fn process_data(data: &[u8]) -> Result<Output, Error> {
+    if data.is_empty() {
+        // Error path inlined into hot function
+        return Err(Error::Empty {
+            context: format!("Expected data, got empty slice"),
+            suggestions: vec!["Check input", "Validate before calling"],
+        });
+    }
+    
+    // Hot path - now polluted with error construction code
+    do_processing(data)
+}
+```
+
+## Good
+
+```rust
+fn process_data(data: &[u8]) -> Result<Output, Error> {
+    if data.is_empty() {
+        return Err(empty_data_error());  // Cold path stays small
+    }
+    
+    do_processing(data)
+}
+
+#[cold]
+#[inline(never)]
+fn empty_data_error() -> Error {
+    Error::Empty {
+        context: format!("Expected data, got empty slice"),
+        suggestions: vec!["Check input", "Validate before calling"],
+    }
+}
+```
+
+## #[cold] for Unlikely Branches
+
+```rust
+fn parse_value(input: &str) -> Result<i32, ParseError> {
+    match input.parse() {
+        Ok(n) => Ok(n),
+        Err(e) => cold_parse_error(input, e),
+    }
+}
+
+#[cold]
+fn cold_parse_error(input: &str, e: std::num::ParseIntError) -> Result<i32, ParseError> {
+    Err(ParseError {
+        input: input.to_string(),
+        source: e,
+    })
+}
+```
+
+## Panic Paths
+
+```rust
+fn get_index(&self, idx: usize) -> &T {
+    if idx >= self.len {
+        cold_out_of_bounds(idx, self.len);
+    }
+    unsafe { self.ptr.add(idx).as_ref().unwrap() }
+}
+
+#[cold]
+#[inline(never)]
+fn cold_out_of_bounds(idx: usize, len: usize) -> ! {
+    panic!("index {} out of bounds for length {}", idx, len);
+}
+```
+
+## Error Construction Functions
+
+```rust
+// Keep error construction out of hot path
+impl MyError {
+    #[cold]
+    pub fn io_error(source: std::io::Error, path: &Path) -> Self {
+        MyError::Io {
+            source,
+            path: path.to_path_buf(),
+            context: get_context(),
+        }
+    }
+    
+    #[cold]
+    pub fn validation_error(msg: &str, field: &str) -> Self {
+        MyError::Validation {
+            message: msg.to_string(),
+            field: field.to_string(),
+        }
+    }
+}
+
+fn read_config(path: &Path) -> Result<Config, MyError> {
+    std::fs::read_to_string(path)
+        .map_err(|e| MyError::io_error(e, path))?
+        .parse()
+        .map_err(|e| MyError::parse_error(e))
+}
+```
+
+## likely/unlikely Hints
+
+```rust
+// Nightly: intrinsics for branch hints
+#![feature(core_intrinsics)]
+use std::intrinsics::{likely, unlikely};
+
+fn process(data: Option<&Data>) -> Result<Output, Error> {
+    if unlikely(data.is_none()) {
+        return cold_none_error();
+    }
+    
+    let data = data.unwrap();
+    
+    if likely(data.is_valid()) {
+        fast_process(data)
+    } else {
+        slow_validate_and_process(data)
+    }
+}
+
+// Stable alternative: structure code so hot path is "fall through"
+fn process(data: Option<&Data>) -> Result<Output, Error> {
+    let data = match data {
+        Some(d) => d,
+        None => return cold_none_error(),  // Early return = unlikely hint
+    };
+    
+    // Compiler assumes code after early returns is "hot"
+    fast_process(data)
+}
+```
+
+## Pattern: Extract Cold Code
+
+```rust
+// Before: cold code inline
+fn hot_function(x: i32) -> i32 {
+    if x < 0 {
+        log::error!("Negative value: {}", x);
+        eprintln!("Debug info: {:?}", std::backtrace::Backtrace::capture());
+        return 0;
+    }
+    x * 2
+}
+
+// After: cold code extracted
+fn hot_function(x: i32) -> i32 {
+    if x < 0 {
+        return handle_negative(x);
+    }
+    x * 2
+}
+
+#[cold]
+#[inline(never)]
+fn handle_negative(x: i32) -> i32 {
+    log::error!("Negative value: {}", x);
+    eprintln!("Debug info: {:?}", std::backtrace::Backtrace::capture());
+    0
+}
+```
+
+## See Also
+
+- [opt-inline-small](./opt-inline-small.md) - Inlining for hot code
+- [opt-inline-always-rare](./opt-inline-always-rare.md) - Forced inlining
+- [err-result-over-panic](./err-result-over-panic.md) - Error handling patterns