agy-superpowers 5.2.2 → 5.2.3

package/template/agent/skills/rust-developer/references/rust-rules/err-question-mark.md

@@ -1,151 +0,0 @@
-# err-question-mark
-
-> Use `?` operator for clean propagation
-
-## Why It Matters
-
-The `?` operator is Rust's idiomatic way to propagate errors. It's concise, readable, and automatically converts between compatible error types using `From`. It replaces verbose `match` or `unwrap()` calls.
-
-## Bad
-
-```rust
-// Verbose match-based error handling
-fn load_config() -> Result<Config, Error> {
-    let content = match std::fs::read_to_string("config.toml") {
-        Ok(c) => c,
-        Err(e) => return Err(Error::Io(e)),
-    };
-    
-    let config = match toml::from_str(&content) {
-        Ok(c) => c,
-        Err(e) => return Err(Error::Parse(e)),
-    };
-    
-    Ok(config)
-}
-
-// Or worse - using unwrap
-fn load_config_bad() -> Config {
-    let content = std::fs::read_to_string("config.toml").unwrap();
-    toml::from_str(&content).unwrap()
-}
-```
-
-## Good
-
-```rust
-fn load_config() -> Result<Config, Error> {
-    let content = std::fs::read_to_string("config.toml")?;
-    let config = toml::from_str(&content)?;
-    Ok(config)
-}
-
-// Even more concise
-fn load_config() -> Result<Config, Error> {
-    Ok(toml::from_str(&std::fs::read_to_string("config.toml")?)?)
-}
-```
-
-## How ? Works
-
-```rust
-// This:
-let x = expr?;
-
-// Expands roughly to:
-let x = match expr {
-    Ok(val) => val,
-    Err(err) => return Err(From::from(err)),
-};
-```
-
-## Combining with Context
-
-```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)
-        .context("failed to parse user JSON")?;
-    
-    Ok(user)
-}
-```
-
-## ? with Option
-
-```rust
-fn get_first_word(text: &str) -> Option<&str> {
-    let first_line = text.lines().next()?;
-    let first_word = first_line.split_whitespace().next()?;
-    Some(first_word)
-}
-
-// Convert Option to Result
-fn get_required_config(key: &str) -> Result<String, Error> {
-    config.get(key)
-        .cloned()
-        .ok_or_else(|| Error::MissingConfig(key.to_string()))
-}
-```
-
-## Error Type Conversion
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-enum MyError {
-    #[error("io error")]
-    Io(#[from] std::io::Error),  // Auto From impl
-    
-    #[error("parse error")]
-    Parse(#[from] serde_json::Error),  // Auto From impl
-}
-
-fn process() -> Result<(), MyError> {
-    // ? automatically converts io::Error to MyError via From
-    let content = std::fs::read_to_string("file.txt")?;
-    
-    // ? automatically converts serde_json::Error to MyError
-    let data: Data = serde_json::from_str(&content)?;
-    
-    Ok(())
-}
-```
-
-## In main()
-
-```rust
-// Option 1: Return Result from main
-fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let config = load_config()?;
-    run_app(config)?;
-    Ok(())
-}
-
-// Option 2: Handle in main, exit on error
-fn main() {
-    if let Err(e) = run() {
-        eprintln!("Error: {:#}", e);
-        std::process::exit(1);
-    }
-}
-
-fn run() -> anyhow::Result<()> {
-    let config = load_config()?;
-    run_app(config)?;
-    Ok(())
-}
-```
-
-## See Also
-
-- [err-context-chain](err-context-chain.md) - Add context with .context()
-- [err-from-impl](err-from-impl.md) - Use #[from] for automatic conversion
-- [err-anyhow-app](err-anyhow-app.md) - Use anyhow for applications

package/template/agent/skills/rust-developer/references/rust-rules/err-result-over-panic.md

@@ -1,130 +0,0 @@
-# err-result-over-panic
-
-> Return `Result<T, E>` instead of panicking for recoverable errors
-
-## Why It Matters
-
-Panics unwind the stack and crash the thread (or program). They're unrecoverable from the caller's perspective. `Result<T, E>` gives callers the ability to decide how to handle errors—retry, fallback, propagate, or log. Libraries should almost never panic; applications should minimize panics to truly unrecoverable situations.
-
-## Bad
-
-```rust
-fn parse_config(path: &str) -> Config {
-    let content = std::fs::read_to_string(path)
-        .expect("Failed to read config");  // Crashes on missing file
-    
-    serde_json::from_str(&content)
-        .expect("Invalid config format")   // Crashes on bad JSON
-}
-
-fn divide(a: i32, b: i32) -> i32 {
-    if b == 0 {
-        panic!("Division by zero!");  // Crashes the program
-    }
-    a / b
-}
-```
-
-Caller has no chance to recover or provide a fallback.
-
-## Good
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-enum ConfigError {
-    #[error("Failed to read config file: {0}")]
-    Io(#[from] std::io::Error),
-    #[error("Invalid config format: {0}")]
-    Parse(#[from] serde_json::Error),
-}
-
-fn parse_config(path: &str) -> Result<Config, ConfigError> {
-    let content = std::fs::read_to_string(path)?;
-    let config = serde_json::from_str(&content)?;
-    Ok(config)
-}
-
-fn divide(a: i32, b: i32) -> Result<i32, &'static str> {
-    if b == 0 {
-        return Err("Division by zero");
-    }
-    Ok(a / b)
-}
-
-// Caller decides how to handle
-match parse_config("app.json") {
-    Ok(config) => run_app(config),
-    Err(e) => {
-        eprintln!("Using default config: {}", e);
-        run_app(Config::default())
-    }
-}
-```
-
-## When Panic IS Appropriate
-
-```rust
-// 1. Bug in the program (invariant violation)
-fn get_cached_value(&self, key: &str) -> &Value {
-    self.cache.get(key).expect("BUG: key was verified to exist")
-}
-
-// 2. Setup/initialization that can't reasonably fail
-fn main() {
-    let config = Config::load().expect("Failed to load required config");
-    // Can't run without config, panic is reasonable
-}
-
-// 3. Tests
-#[test]
-fn test_parse() {
-    let result = parse("valid input").unwrap(); // unwrap OK in tests
-    assert_eq!(result, expected);
-}
-
-// 4. Examples and prototypes
-fn main() {
-    // Quick prototype, panic is fine
-    let data = fetch_data().unwrap();
-}
-```
-
-## Panic vs Result Decision Guide
-
-| Situation | Use |
-|-----------|-----|
-| File not found | `Result` |
-| Network error | `Result` |
-| Invalid user input | `Result` |
-| Parse error | `Result` |
-| Index out of bounds (from user data) | `Result` |
-| Index out of bounds (internal bug) | Panic |
-| Violated internal invariant | Panic |
-| Unimplemented code path | Panic (`unimplemented!()`) |
-| Impossible state reached | Panic (`unreachable!()`) |
-
-## Library vs Application
-
-```rust
-// Library: NEVER panic on user input
-pub fn parse(input: &str) -> Result<Ast, ParseError> {
-    // Always return Result
-}
-
-// Application: Can panic at top level for critical failures
-fn main() {
-    if let Err(e) = run() {
-        eprintln!("Fatal error: {}", e);
-        std::process::exit(1);
-    }
-}
-```
-
-## See Also
-
-- [err-thiserror-lib](./err-thiserror-lib.md) - Define error types for libraries
-- [err-anyhow-app](./err-anyhow-app.md) - Ergonomic errors for applications
-- [err-no-unwrap-prod](./err-no-unwrap-prod.md) - Avoid unwrap in production code
-- [anti-unwrap-abuse](./anti-unwrap-abuse.md) - When unwrap is acceptable

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

@@ -1,155 +0,0 @@
-# err-source-chain
-
-> Preserve error chains with `#[source]` or `source()` method
-
-## Why It Matters
-
-Errors often have underlying causes. Preserving the error chain (via `source()` method) allows logging frameworks and error reporters to show the full context: "config parse failed → JSON syntax error at line 5 → unexpected token". Without chaining, you lose valuable debugging information.
-
-## Bad
-
-```rust
-#[derive(Debug)]
-enum ConfigError {
-    ParseFailed(String),  // Lost the original serde_json::Error
-}
-
-fn load_config(path: &str) -> Result<Config, ConfigError> {
-    let content = std::fs::read_to_string(path)
-        .map_err(|e| ConfigError::ParseFailed(e.to_string()))?;  // Chain lost!
-    
-    serde_json::from_str(&content)
-        .map_err(|e| ConfigError::ParseFailed(e.to_string()))?  // No source
-}
-
-// Error output: "Parse failed: invalid type: ..."
-// Missing: which file? what line? what was the parent error?
-```
-
-## Good
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-enum ConfigError {
-    #[error("Failed to read config file '{path}'")]
-    ReadFailed {
-        path: String,
-        #[source]  // Preserves the error chain
-        source: std::io::Error,
-    },
-    
-    #[error("Failed to parse config file '{path}'")]
-    ParseFailed {
-        path: String,
-        #[source]  // Original parse error preserved
-        source: serde_json::Error,
-    },
-}
-
-fn load_config(path: &str) -> Result<Config, ConfigError> {
-    let content = std::fs::read_to_string(path)
-        .map_err(|source| ConfigError::ReadFailed {
-            path: path.to_string(),
-            source,  // Chain preserved
-        })?;
-    
-    serde_json::from_str(&content)
-        .map_err(|source| ConfigError::ParseFailed {
-            path: path.to_string(),
-            source,
-        })
-}
-```
-
-## Manual source() Implementation
-
-```rust
-use std::error::Error;
-
-#[derive(Debug)]
-struct MyError {
-    message: String,
-    source: Option<Box<dyn Error + Send + Sync>>,
-}
-
-impl std::fmt::Display for MyError {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(f, "{}", self.message)
-    }
-}
-
-impl Error for MyError {
-    fn source(&self) -> Option<&(dyn Error + 'static)> {
-        self.source.as_ref().map(|e| e.as_ref() as &(dyn Error + 'static))
-    }
-}
-```
-
-## Walking the Error Chain
-
-```rust
-fn print_error_chain(error: &dyn std::error::Error) {
-    eprintln!("Error: {}", error);
-    
-    let mut source = error.source();
-    while let Some(err) = source {
-        eprintln!("Caused by: {}", err);
-        source = err.source();
-    }
-}
-
-// With anyhow, use {:?} for full chain
-let result: anyhow::Result<()> = do_something();
-if let Err(e) = result {
-    eprintln!("{:?}", e);  // Prints full chain with backtraces
-}
-```
-
-## anyhow Context
-
-```rust
-use anyhow::{Context, Result};
-
-fn load_config(path: &str) -> Result<Config> {
-    let content = std::fs::read_to_string(path)
-        .with_context(|| format!("Failed to read '{}'", path))?;
-    
-    let config: Config = serde_json::from_str(&content)
-        .with_context(|| format!("Failed to parse '{}'", path))?;
-    
-    Ok(config)
-}
-
-// Output:
-// Error: Failed to parse 'config.json'
-// Caused by: expected `:` at line 5 column 10
-```
-
-## #[from] vs #[source]
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-enum MyError {
-    // #[from] = implements From + sets source
-    #[error("IO error")]
-    Io(#[from] std::io::Error),
-    
-    // #[source] = only sets source (no From impl)
-    #[error("Parse error in file '{path}'")]
-    Parse {
-        path: String,
-        #[source]
-        source: serde_json::Error,
-    },
-}
-```
-
-## See Also
-
-- [err-thiserror-lib](./err-thiserror-lib.md) - thiserror for error definitions
-- [err-context-chain](./err-context-chain.md) - Adding context to errors
-- [err-from-impl](./err-from-impl.md) - From implementations for ?

package/template/agent/skills/rust-developer/references/rust-rules/err-thiserror-lib.md

@@ -1,171 +0,0 @@
-# err-thiserror-lib
-
-> Use `thiserror` for library error types
-
-## Why It Matters
-
-Libraries should expose typed, matchable errors so users can handle specific error conditions. `thiserror` generates `Error` trait implementations with minimal boilerplate, creating ergonomic error types that are easy to match against.
-
-## Bad
-
-```rust
-// String errors - not matchable
-fn parse(input: &str) -> Result<Data, String> {
-    Err("parse error".to_string())
-}
-
-// Box<dyn Error> - not matchable
-fn load(path: &Path) -> Result<Data, Box<dyn std::error::Error>> {
-    Err(Box::new(std::io::Error::new(std::io::ErrorKind::NotFound, "file not found")))
-}
-
-// Manual implementation - verbose
-#[derive(Debug)]
-enum MyError {
-    Io(std::io::Error),
-    Parse(String),
-}
-
-impl std::fmt::Display for MyError {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        match self {
-            MyError::Io(e) => write!(f, "io error: {}", e),
-            MyError::Parse(s) => write!(f, "parse error: {}", s),
-        }
-    }
-}
-
-impl std::error::Error for MyError {
-    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
-        match self {
-            MyError::Io(e) => Some(e),
-            MyError::Parse(_) => None,
-        }
-    }
-}
-```
-
-## Good
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-pub enum ParseError {
-    #[error("invalid syntax at line {line}: {message}")]
-    Syntax { line: usize, message: String },
-    
-    #[error("unexpected end of file")]
-    UnexpectedEof,
-    
-    #[error("invalid utf-8 encoding")]
-    Utf8(#[from] std::str::Utf8Error),
-    
-    #[error("io error reading input")]
-    Io(#[from] std::io::Error),
-}
-
-// Usage
-fn parse(input: &str) -> Result<Ast, ParseError> {
-    if input.is_empty() {
-        return Err(ParseError::UnexpectedEof);
-    }
-    // ...
-}
-
-// Users can match specific errors
-match parse(input) {
-    Ok(ast) => process(ast),
-    Err(ParseError::Syntax { line, message }) => {
-        eprintln!("Syntax error on line {}: {}", line, message);
-    }
-    Err(ParseError::UnexpectedEof) => {
-        eprintln!("File ended unexpectedly");
-    }
-    Err(e) => eprintln!("Error: {}", e),
-}
-```
-
-## Key Attributes
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-pub enum MyError {
-    // Simple message
-    #[error("operation failed")]
-    Failed,
-    
-    // Interpolated fields
-    #[error("invalid value: {0}")]
-    InvalidValue(String),
-    
-    // Named fields
-    #[error("connection to {host}:{port} failed")]
-    Connection { host: String, port: u16 },
-    
-    // Automatic From impl with #[from]
-    #[error("database error")]
-    Database(#[from] sqlx::Error),
-    
-    // Source without From (manual conversion needed)
-    #[error("validation failed")]
-    Validation {
-        #[source]
-        cause: ValidationError,
-        field: String,
-    },
-    
-    // Transparent - delegates Display and source to inner
-    #[error(transparent)]
-    Other(#[from] anyhow::Error),
-}
-```
-
-## Error Chaining
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-pub enum ConfigError {
-    #[error("failed to read config file")]
-    Read(#[source] std::io::Error),
-    
-    #[error("failed to parse config")]
-    Parse(#[source] toml::de::Error),
-    
-    #[error("invalid config value for '{key}'")]
-    InvalidValue {
-        key: String,
-        #[source]
-        cause: ValueError,
-    },
-}
-
-// Error chain is preserved
-fn load_config(path: &Path) -> Result<Config, ConfigError> {
-    let content = std::fs::read_to_string(path)
-        .map_err(ConfigError::Read)?;
-    
-    let config: Config = toml::from_str(&content)
-        .map_err(ConfigError::Parse)?;
-    
-    Ok(config)
-}
-```
-
-## Library vs Application
-
-| Context | Crate | Why |
-|---------|-------|-----|
-| Library | `thiserror` | Typed errors users can match |
-| Application | `anyhow` | Easy error handling with context |
-| Both | `thiserror` for public API, `anyhow` internally | Best of both |
-
-## See Also
-
-- [err-anyhow-app](err-anyhow-app.md) - Use anyhow for applications
-- [err-from-impl](err-from-impl.md) - Use #[from] for automatic conversion
-- [err-source-chain](err-source-chain.md) - Use #[source] to chain errors