agy-superpowers 5.2.1 → 5.2.3

package/template/agent/skills/rust-developer/references/rust-rules/err-anyhow-app.md

@@ -1,179 +0,0 @@
-# err-anyhow-app
-
-> Use `anyhow` for application error handling
-
-## Why It Matters
-
-Applications often don't need typed errors - they just need to report what went wrong with good context. `anyhow` provides easy error handling with context chaining, backtraces, and conversion from any error type.
-
-## Bad
-
-```rust
-// Tedious type management
-fn load_config() -> Result<Config, Box<dyn std::error::Error>> {
-    let path = find_config()?;  // Returns FindError
-    let content = std::fs::read_to_string(&path)?;  // Returns io::Error
-    let config: Config = toml::from_str(&content)?;  // Returns toml::Error
-    validate(&config)?;  // Returns ValidationError
-    Ok(config)
-}
-
-// No context - hard to debug
-fn process() -> Result<(), Box<dyn std::error::Error>> {
-    let data = fetch()?;  // Which fetch failed?
-    transform(data)?;     // What was being transformed?
-    save()?;              // Where was it saving to?
-    Ok(())
-}
-```
-
-## Good
-
-```rust
-use anyhow::{Context, Result};
-
-fn load_config() -> Result<Config> {
-    let path = find_config()
-        .context("failed to locate config file")?;
-    
-    let content = std::fs::read_to_string(&path)
-        .with_context(|| format!("failed to read config from {}", path.display()))?;
-    
-    let config: Config = toml::from_str(&content)
-        .context("failed to parse config as TOML")?;
-    
-    validate(&config)
-        .context("config validation failed")?;
-    
-    Ok(config)
-}
-
-// Error message: "config validation failed: field 'port' must be > 0"
-// Full chain preserved for debugging
-```
-
-## Key Features
-
-```rust
-use anyhow::{anyhow, bail, ensure, Context, Result};
-
-fn example() -> Result<()> {
-    // Create ad-hoc errors
-    let err = anyhow!("something went wrong");
-    
-    // Early return with error
-    bail!("aborting due to {}", reason);
-    
-    // Assert with error
-    ensure!(condition, "condition was false");
-    
-    // Add context to any error
-    risky_operation()
-        .context("risky operation failed")?;
-    
-    // Dynamic context
-    fetch(url)
-        .with_context(|| format!("failed to fetch {}", url))?;
-    
-    Ok(())
-}
-```
-
-## Main Function Pattern
-
-```rust
-use anyhow::Result;
-
-fn main() -> Result<()> {
-    let config = load_config()?;
-    run_app(config)?;
-    Ok(())
-}
-
-// Or with custom exit handling
-fn main() {
-    if let Err(e) = run() {
-        eprintln!("Error: {:#}", e);  // Pretty-print with causes
-        std::process::exit(1);
-    }
-}
-
-fn run() -> Result<()> {
-    // Application logic
-    Ok(())
-}
-```
-
-## Error Display Formats
-
-```rust
-use anyhow::Result;
-
-fn show_error(err: anyhow::Error) {
-    // Just the top-level message
-    println!("{}", err);
-    // "config validation failed"
-    
-    // With cause chain (# alternate format)
-    println!("{:#}", err);
-    // "config validation failed: field 'port' must be > 0"
-    
-    // Debug format with backtrace
-    println!("{:?}", err);
-    // Full backtrace if RUST_BACKTRACE=1
-    
-    // Iterate through cause chain
-    for cause in err.chain() {
-        println!("Caused by: {}", cause);
-    }
-}
-```
-
-## Combining with thiserror
-
-```rust
-// In your library crate - typed errors
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-pub enum ApiError {
-    #[error("rate limited")]
-    RateLimited,
-    #[error("not found: {0}")]
-    NotFound(String),
-}
-
-// In your application - anyhow for handling
-use anyhow::{Context, Result};
-
-fn fetch_user(id: u64) -> Result<User> {
-    api::get_user(id)
-        .with_context(|| format!("failed to fetch user {}", id))
-}
-
-// Can still downcast if needed
-fn handle_error(err: anyhow::Error) {
-    if let Some(api_err) = err.downcast_ref::<ApiError>() {
-        match api_err {
-            ApiError::RateLimited => wait_and_retry(),
-            ApiError::NotFound(id) => log_missing(id),
-        }
-    }
-}
-```
-
-## When to Use Which
-
-| Situation | Use |
-|-----------|-----|
-| Library public API | `thiserror` |
-| Application code | `anyhow` |
-| CLI tools | `anyhow` |
-| Internal library code | Either |
-| Need to match error variants | `thiserror` |
-| Just need to report errors | `anyhow` |
-
-## See Also
-
-- [err-thiserror-lib](err-thiserror-lib.md) - Use thiserror for libraries
-- [err-context-chain](err-context-chain.md) - Add context to errors

package/template/agent/skills/rust-developer/references/rust-rules/err-context-chain.md

@@ -1,144 +0,0 @@
-# err-context-chain
-
-> Add context with `.context()` or `.with_context()`
-
-## Why It Matters
-
-Raw errors often lack information about what operation failed. Adding context creates an error chain that tells the full story: what you were trying to do, and why it failed.
-
-## Bad
-
-```rust
-// Raw error - no context
-fn load_user(id: u64) -> Result<User, Error> {
-    let path = format!("users/{}.json", id);
-    let content = std::fs::read_to_string(&path)?;
-    Ok(serde_json::from_str(&content)?)
-}
-
-// Error message: "No such file or directory (os error 2)"
-// Which file? What were we doing?
-```
-
-## Good
-
-```rust
-use anyhow::{Context, Result};
-
-fn load_user(id: u64) -> Result<User> {
-    let path = format!("users/{}.json", id);
-    
-    let content = std::fs::read_to_string(&path)
-        .with_context(|| format!("failed to read user file: {}", path))?;
-    
-    let user: User = serde_json::from_str(&content)
-        .with_context(|| format!("failed to parse user {} JSON", id))?;
-    
-    Ok(user)
-}
-
-// Error: "failed to parse user 42 JSON"
-// Caused by: "expected ':' at line 5 column 12"
-```
-
-## context() vs with_context()
-
-```rust
-// context() - static string (slight allocation)
-fs::read_to_string(path)
-    .context("failed to read config")?;
-
-// with_context() - lazy evaluation (only allocates on error)
-fs::read_to_string(path)
-    .with_context(|| format!("failed to read {}", path))?;
-
-// Use with_context() when:
-// - Message includes runtime data (format!)
-// - Computing the message is expensive
-// - Error path is cold (most of the time)
-```
-
-## Building Context Chains
-
-```rust
-fn process_order(order_id: u64) -> Result<()> {
-    let order = fetch_order(order_id)
-        .with_context(|| format!("failed to fetch order {}", order_id))?;
-    
-    let user = load_user(order.user_id)
-        .with_context(|| format!("failed to load user for order {}", order_id))?;
-    
-    let payment = process_payment(&order, &user)
-        .context("payment processing failed")?;
-    
-    ship_order(&order, &payment)
-        .context("shipping failed")?;
-    
-    Ok(())
-}
-
-// Full error chain:
-// "shipping failed"
-// Caused by: "carrier API returned 503"
-// Caused by: "connection refused"
-```
-
-## Displaying Error Chains
-
-```rust
-fn main() {
-    if let Err(e) = run() {
-        // Just top-level message
-        eprintln!("Error: {}", e);
-        
-        // Full chain with alternate format
-        eprintln!("Error: {:#}", e);
-        
-        // Debug format (includes backtrace if enabled)
-        eprintln!("Error: {:?}", e);
-        
-        // Iterate through chain
-        for (i, cause) in e.chain().enumerate() {
-            eprintln!("  {}: {}", i, cause);
-        }
-    }
-}
-```
-
-## With thiserror
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-pub enum AppError {
-    #[error("failed to load config from {path}")]
-    ConfigLoad {
-        path: String,
-        #[source]
-        cause: std::io::Error,
-    },
-    
-    #[error("failed to connect to database")]
-    Database {
-        #[source]
-        cause: sqlx::Error,
-    },
-}
-
-// Usage
-fn load_config(path: &str) -> Result<Config, AppError> {
-    let content = std::fs::read_to_string(path)
-        .map_err(|e| AppError::ConfigLoad {
-            path: path.to_string(),
-            cause: e,
-        })?;
-    // ...
-}
-```
-
-## See Also
-
-- [err-anyhow-app](err-anyhow-app.md) - Use anyhow for applications
-- [err-source-chain](err-source-chain.md) - Use #[source] to chain errors
-- [err-question-mark](err-question-mark.md) - Use ? for propagation

package/template/agent/skills/rust-developer/references/rust-rules/err-custom-type.md

@@ -1,152 +0,0 @@
-# err-custom-type
-
-> Define custom error types for domain-specific failures
-
-## Why It Matters
-
-Generic errors like `String`, `Box<dyn Error>`, or catch-all enums obscure what can actually go wrong. Custom error types document failure modes in the type system, enable pattern matching for specific handling, and provide clear API contracts. They make your code self-documenting and help callers handle errors appropriately.
-
-## Bad
-
-```rust
-// Generic string errors - no structure
-fn validate_user(user: &User) -> Result<(), String> {
-    if user.name.is_empty() {
-        return Err("Name is empty".to_string());
-    }
-    if user.age > 150 {
-        return Err("Age is invalid".to_string());
-    }
-    Ok(())
-}
-
-// Caller can't match on specific errors
-match validate_user(&user) {
-    Ok(()) => save(user),
-    Err(msg) => {
-        // Can only do string comparison - fragile!
-        if msg.contains("Name") {
-            prompt_for_name()
-        }
-    }
-}
-```
-
-## Good
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-pub enum ValidationError {
-    #[error("name cannot be empty")]
-    EmptyName,
-    
-    #[error("name exceeds maximum length of {max} characters")]
-    NameTooLong { max: usize, actual: usize },
-    
-    #[error("invalid age {0}: must be between 0 and 150")]
-    InvalidAge(u8),
-    
-    #[error("email format is invalid: {0}")]
-    InvalidEmail(String),
-}
-
-fn validate_user(user: &User) -> Result<(), ValidationError> {
-    if user.name.is_empty() {
-        return Err(ValidationError::EmptyName);
-    }
-    if user.name.len() > 100 {
-        return Err(ValidationError::NameTooLong { 
-            max: 100, 
-            actual: user.name.len() 
-        });
-    }
-    if user.age > 150 {
-        return Err(ValidationError::InvalidAge(user.age));
-    }
-    Ok(())
-}
-
-// Caller can match specifically
-match validate_user(&user) {
-    Ok(()) => save(user),
-    Err(ValidationError::EmptyName) => prompt_for_name(),
-    Err(ValidationError::InvalidAge(age)) => {
-        show_error(&format!("Please enter a valid age (you entered {})", age))
-    }
-    Err(e) => show_error(&e.to_string()),
-}
-```
-
-## Error Type Design Guidelines
-
-```rust
-// 1. Group related errors in domain-specific enums
-#[derive(Error, Debug)]
-pub enum AuthError {
-    #[error("invalid credentials")]
-    InvalidCredentials,
-    #[error("account locked after {attempts} failed attempts")]
-    AccountLocked { attempts: u32 },
-    #[error("token expired")]
-    TokenExpired,
-}
-
-#[derive(Error, Debug)]
-pub enum PaymentError {
-    #[error("insufficient funds: need {required}, have {available}")]
-    InsufficientFunds { required: Decimal, available: Decimal },
-    #[error("card declined: {reason}")]
-    CardDeclined { reason: String },
-}
-
-// 2. Include relevant data for error handling/display
-#[derive(Error, Debug)]
-pub enum FileError {
-    #[error("file not found: {path}")]
-    NotFound { path: PathBuf },
-    #[error("permission denied for {path}")]
-    PermissionDenied { path: PathBuf },
-}
-
-// 3. Consider #[non_exhaustive] for public APIs
-#[derive(Error, Debug)]
-#[non_exhaustive]  // Allows adding variants without breaking changes
-pub enum ApiError {
-    #[error("rate limited")]
-    RateLimited,
-    #[error("not found")]
-    NotFound,
-}
-```
-
-## When to Use What
-
-| Error Pattern | Use Case |
-|---------------|----------|
-| Custom enum | Library with specific failure modes |
-| `thiserror` | Libraries needing `std::error::Error` |
-| `anyhow::Error` | Applications, prototypes |
-| Struct with source | Single error type with wrapped cause |
-
-## Struct-Based Errors
-
-For single error types with rich context:
-
-```rust
-#[derive(Error, Debug)]
-#[error("query failed for table '{table}' with filter '{filter}'")]
-pub struct QueryError {
-    pub table: String,
-    pub filter: String,
-    #[source]
-    pub source: DatabaseError,
-}
-```
-
-## See Also
-
-- [err-thiserror-lib](./err-thiserror-lib.md) - thiserror for error definitions
-- [err-anyhow-app](./err-anyhow-app.md) - When to use anyhow instead
-- [api-non-exhaustive](./api-non-exhaustive.md) - Forward-compatible enums

package/template/agent/skills/rust-developer/references/rust-rules/err-doc-errors.md

@@ -1,145 +0,0 @@
-# err-doc-errors
-
-> Document error conditions with `# Errors` section in doc comments
-
-## Why It Matters
-
-Users of your API need to know what can go wrong and why. The `# Errors` documentation section is the standard Rust convention for describing when a function returns `Err`. Good error documentation helps callers handle errors appropriately and understand the contract of your API.
-
-## Bad
-
-```rust
-/// Loads a configuration from the specified path.
-pub fn load_config(path: &Path) -> Result<Config, ConfigError> {
-    // No documentation of error conditions
-    // Caller must read source code to understand what can fail
-}
-
-/// Parses and validates the input string.
-/// 
-/// Returns the parsed value.  // What about errors?
-pub fn parse_input(input: &str) -> Result<Value, ParseError> {
-    // ...
-}
-```
-
-## Good
-
-```rust
-/// Loads a configuration from the specified path.
-///
-/// # Errors
-///
-/// Returns an error if:
-/// - The file at `path` does not exist or cannot be read
-/// - The file contents are not valid TOML
-/// - Required configuration keys are missing
-/// - Configuration values are out of valid ranges
-///
-/// # Examples
-///
-/// ```
-/// # use mylib::{load_config, ConfigError};
-/// # fn main() -> Result<(), ConfigError> {
-/// let config = load_config("app.toml")?;
-/// # Ok(())
-/// # }
-/// ```
-pub fn load_config(path: &Path) -> Result<Config, ConfigError> {
-    // ...
-}
-
-/// Parses and validates the input string as a positive integer.
-///
-/// # Errors
-///
-/// Returns [`ParseError::Empty`] if the input is empty.
-/// Returns [`ParseError::InvalidFormat`] if the input contains non-digit characters.
-/// Returns [`ParseError::Overflow`] if the value exceeds `i64::MAX`.
-/// Returns [`ParseError::NotPositive`] if the value is zero or negative.
-pub fn parse_positive_int(input: &str) -> Result<i64, ParseError> {
-    // ...
-}
-```
-
-## Linking to Error Variants
-
-```rust
-/// Attempts to connect to the database.
-///
-/// # Errors
-///
-/// This function will return an error if:
-///
-/// - [`DbError::ConnectionFailed`] - The database server is unreachable
-/// - [`DbError::AuthenticationFailed`] - Invalid credentials
-/// - [`DbError::Timeout`] - Connection attempt exceeded timeout
-/// - [`DbError::TlsError`] - TLS handshake failed
-///
-/// See [`DbError`] for more details on each variant.
-pub fn connect(config: &DbConfig) -> Result<Connection, DbError> {
-    // ...
-}
-```
-
-## Panic vs Error Documentation
-
-```rust
-/// Divides two numbers.
-///
-/// # Errors
-///
-/// Returns [`MathError::DivisionByZero`] if `divisor` is zero.
-///
-/// # Panics
-///
-/// Panics if called from a non-main thread (debug builds only).
-pub fn divide(dividend: i64, divisor: i64) -> Result<i64, MathError> {
-    // ...
-}
-```
-
-## Error Section Format Options
-
-```rust
-// Style 1: Bullet list (good for multiple conditions)
-/// # Errors
-///
-/// Returns an error if:
-/// - The file does not exist
-/// - The file cannot be read
-/// - The content is invalid UTF-8
-
-// Style 2: Returns statements (good for mapping to variants)
-/// # Errors
-///
-/// Returns [`Error::NotFound`] if the item doesn't exist.
-/// Returns [`Error::PermissionDenied`] if access is forbidden.
-
-// Style 3: Prose (good for complex conditions)
-/// # Errors
-///
-/// This function returns an error when the input fails validation.
-/// Validation includes checking that all required fields are present,
-/// that numeric fields are within allowed ranges, and that string
-/// fields match their expected formats.
-```
-
-## Clippy Lint
-
-```toml
-# Cargo.toml - require error documentation
-[lints.clippy]
-missing_errors_doc = "warn"
-```
-
-```rust
-// This will warn without # Errors section
-pub fn might_fail() -> Result<(), Error> { Ok(()) }
-```
-
-## See Also
-
-- [doc-examples-section](./doc-examples-section.md) - Examples in documentation
-- [err-thiserror-lib](./err-thiserror-lib.md) - Defining error types
-- [api-must-use](./api-must-use.md) - Marking Results as must_use