agy-superpowers 5.2.1 → 5.2.3

package/template/agent/skills/rust-developer/references/rust-rules/err-expect-bugs-only.md

@@ -1,133 +0,0 @@
-# err-expect-bugs-only
-
-> Use `expect()` only for invariants that indicate bugs, not user errors
-
-## Why It Matters
-
-`expect()` is better than `unwrap()` because it provides context, but it still panics. Reserve it for situations where failure indicates a bug in your code—a violated invariant, not a user error or external failure. The message should explain why the invariant should hold, helping future developers understand and fix the bug.
-
-## Bad
-
-```rust
-// User input can legitimately fail - don't expect
-fn parse_user_input(input: &str) -> Config {
-    serde_json::from_str(input)
-        .expect("Invalid JSON")  // User error, not a bug!
-}
-
-// Network can fail - don't expect
-fn fetch_data(url: &str) -> Data {
-    reqwest::get(url)
-        .expect("Network request failed")  // External failure!
-        .json()
-        .expect("Invalid response")
-}
-
-// File might not exist - don't expect
-fn load_config() -> Config {
-    let content = fs::read_to_string("config.json")
-        .expect("Config file missing");  // Environment issue!
-}
-```
-
-## Good
-
-```rust
-// Invariant: after insert, key exists
-fn cache_and_get(&mut self, key: String, value: Value) -> &Value {
-    self.cache.insert(key.clone(), value);
-    self.cache.get(&key)
-        .expect("BUG: key must exist immediately after insert")
-}
-
-// Invariant: regex is compile-time constant
-fn create_parser() -> Regex {
-    Regex::new(r"^\d{4}-\d{2}-\d{2}$")
-        .expect("BUG: date regex is invalid - this is a compile-time constant")
-}
-
-// Invariant: already validated
-fn process_validated(data: ValidatedData) -> Result<Output, ProcessError> {
-    let value = data.required_field
-        .expect("BUG: ValidatedData guarantees required_field is Some");
-    // ...
-}
-
-// Invariant: type system guarantees
-fn get_first<T>(vec: Vec<T>) -> T 
-where 
-    Vec<T>: NonEmpty,  // Hypothetical trait
-{
-    vec.into_iter().next()
-        .expect("BUG: NonEmpty Vec cannot be empty")
-}
-```
-
-## expect() Message Guidelines
-
-Messages should:
-1. Start with "BUG:" or similar to indicate it's an invariant
-2. Explain WHY the invariant should hold
-3. Help developers fix the issue
-
-```rust
-// ❌ Bad messages
-.expect("failed")                    // No context
-.expect("should not be None")        // Doesn't explain why
-.expect("Invalid state")             // Vague
-
-// ✅ Good messages
-.expect("BUG: HashMap entry exists after insert")
-.expect("BUG: validated input must parse - validation is broken")
-.expect("BUG: static regex compilation failed - regex syntax error in source")
-```
-
-## Pattern: Validate Once, expect() After
-
-```rust
-struct ValidatedEmail(String);
-
-impl ValidatedEmail {
-    pub fn new(email: &str) -> Result<Self, EmailError> {
-        // Validation happens here, returns Result
-        if !is_valid_email(email) {
-            return Err(EmailError::Invalid);
-        }
-        Ok(ValidatedEmail(email.to_string()))
-    }
-    
-    pub fn domain(&self) -> &str {
-        // After validation, expect() is fine
-        self.0.split('@').nth(1)
-            .expect("BUG: ValidatedEmail must contain @")
-    }
-}
-```
-
-## Alternatives When expect() Is Wrong
-
-```rust
-// Don't: expect on user data
-let port: u16 = input.parse().expect("Invalid port");
-
-// Do: Return Result
-let port: u16 = input.parse().map_err(|_| ConfigError::InvalidPort)?;
-
-// Do: Provide default
-let port: u16 = input.parse().unwrap_or(8080);
-
-// Do: Handle explicitly
-let port: u16 = match input.parse() {
-    Ok(p) => p,
-    Err(_) => {
-        log::warn!("Invalid port '{}', using default", input);
-        8080
-    }
-};
-```
-
-## See Also
-
-- [err-no-unwrap-prod](./err-no-unwrap-prod.md) - Avoiding unwrap in production
-- [err-result-over-panic](./err-result-over-panic.md) - When to return Result
-- [api-parse-dont-validate](./api-parse-dont-validate.md) - Type-driven validation

package/template/agent/skills/rust-developer/references/rust-rules/err-from-impl.md

@@ -1,152 +0,0 @@
-# err-from-impl
-
-> Implement `From<E>` for error conversions to enable `?` operator
-
-## Why It Matters
-
-The `?` operator automatically converts errors using `From` trait. By implementing `From<SourceError> for YourError`, you enable seamless error propagation without explicit `.map_err()` calls. This makes error handling code cleaner and ensures consistent error wrapping throughout your codebase.
-
-## Bad
-
-```rust
-#[derive(Debug)]
-enum AppError {
-    Io(std::io::Error),
-    Parse(serde_json::Error),
-    Database(diesel::result::Error),
-}
-
-fn load_config(path: &str) -> Result<Config, AppError> {
-    let content = std::fs::read_to_string(path)
-        .map_err(|e| AppError::Io(e))?;  // Manual conversion everywhere
-    
-    let config: Config = serde_json::from_str(&content)
-        .map_err(|e| AppError::Parse(e))?;  // Repeated boilerplate
-    
-    save_to_db(&config)
-        .map_err(|e| AppError::Database(e))?;  // Gets tedious
-    
-    Ok(config)
-}
-```
-
-## Good
-
-```rust
-#[derive(Debug)]
-enum AppError {
-    Io(std::io::Error),
-    Parse(serde_json::Error),
-    Database(diesel::result::Error),
-}
-
-// Implement From for each source error type
-impl From<std::io::Error> for AppError {
-    fn from(err: std::io::Error) -> Self {
-        AppError::Io(err)
-    }
-}
-
-impl From<serde_json::Error> for AppError {
-    fn from(err: serde_json::Error) -> Self {
-        AppError::Parse(err)
-    }
-}
-
-impl From<diesel::result::Error> for AppError {
-    fn from(err: diesel::result::Error) -> Self {
-        AppError::Database(err)
-    }
-}
-
-fn load_config(path: &str) -> Result<Config, AppError> {
-    let content = std::fs::read_to_string(path)?;  // Auto-converts
-    let config: Config = serde_json::from_str(&content)?;  // Clean!
-    save_to_db(&config)?;
-    Ok(config)
-}
-```
-
-## Use thiserror for Automatic From
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-enum AppError {
-    #[error("IO error: {0}")]
-    Io(#[from] std::io::Error),  // Auto-generates From impl
-    
-    #[error("Parse error: {0}")]
-    Parse(#[from] serde_json::Error),  // #[from] does the work
-    
-    #[error("Database error: {0}")]
-    Database(#[from] diesel::result::Error),
-}
-
-// Now ? just works
-fn load_config(path: &str) -> Result<Config, AppError> {
-    let content = std::fs::read_to_string(path)?;
-    let config: Config = serde_json::from_str(&content)?;
-    save_to_db(&config)?;
-    Ok(config)
-}
-```
-
-## From with Context
-
-Sometimes you need to add context during conversion:
-
-```rust
-#[derive(Error, Debug)]
-enum ConfigError {
-    #[error("Failed to read config from '{path}': {source}")]
-    ReadFailed {
-        path: String,
-        #[source]
-        source: std::io::Error,
-    },
-}
-
-// Can't use #[from] when you need extra context
-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,
-        })?;
-    // ...
-}
-
-// Or use anyhow for ad-hoc context
-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 config from '{}'", path))?;
-    // ...
-}
-```
-
-## Blanket From Implementations
-
-Be careful with blanket implementations:
-
-```rust
-// ❌ Too broad - conflicts with other From impls
-impl<E: std::error::Error> From<E> for AppError {
-    fn from(err: E) -> Self {
-        AppError::Other(err.to_string())
-    }
-}
-
-// ✅ Specific implementations
-impl From<std::io::Error> for AppError { ... }
-impl From<ParseIntError> for AppError { ... }
-```
-
-## See Also
-
-- [err-thiserror-lib](./err-thiserror-lib.md) - Using thiserror for libraries
-- [err-source-chain](./err-source-chain.md) - Preserving error chains
-- [err-question-mark](./err-question-mark.md) - The ? operator

package/template/agent/skills/rust-developer/references/rust-rules/err-lowercase-msg.md

@@ -1,124 +0,0 @@
-# err-lowercase-msg
-
-> Start error messages lowercase, no trailing punctuation
-
-## Why It Matters
-
-Error messages are often chained, logged, or displayed with additional context. Consistent formatting—lowercase start, no trailing period—allows clean composition: "failed to load config: invalid JSON: unexpected token". Mixed case and punctuation create awkward output: "Failed to load config.: Invalid JSON.: Unexpected token.".
-
-## Bad
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-enum ConfigError {
-    #[error("Failed to read config file.")]  // Capital F, trailing period
-    ReadFailed(#[from] std::io::Error),
-    
-    #[error("Invalid JSON format!")]  // Capital I, exclamation
-    ParseFailed(#[from] serde_json::Error),
-    
-    #[error("The requested key was not found")]  // Reads like a sentence
-    KeyNotFound(String),
-}
-
-// Chained output: "Config load error: Failed to read config file.: No such file"
-// Awkward capitalization and punctuation
-```
-
-## Good
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-enum ConfigError {
-    #[error("failed to read config file")]  // lowercase, no period
-    ReadFailed(#[from] std::io::Error),
-    
-    #[error("invalid JSON format")]  // lowercase, no period
-    ParseFailed(#[from] serde_json::Error),
-    
-    #[error("key not found: {0}")]  // lowercase, data at end
-    KeyNotFound(String),
-}
-
-// Chained output: "config load error: failed to read config file: no such file"
-// Clean, consistent
-```
-
-## Rust Standard Library Convention
-
-The standard library follows this convention:
-
-```rust
-// std::io::Error messages
-"entity not found"
-"permission denied"
-"connection refused"
-
-// std::num::ParseIntError
-"invalid digit found in string"
-
-// std::str::Utf8Error  
-"invalid utf-8 sequence"
-```
-
-## Formatting Guidelines
-
-| Do | Don't |
-|----|-------|
-| `"failed to parse config"` | `"Failed to parse config."` |
-| `"invalid input: expected number"` | `"Invalid input - expected a number!"` |
-| `"connection timed out after {0}s"` | `"Connection Timed Out After {0} seconds."` |
-| `"key '{0}' not found"` | `"Key Not Found: {0}"` |
-
-## Context Addition Pattern
-
-```rust
-use anyhow::{Context, Result};
-
-fn load_user(id: u64) -> Result<User> {
-    let data = fetch(id)
-        .with_context(|| format!("failed to fetch user {}", id))?;
-    
-    parse_user(data)
-        .with_context(|| "failed to parse user data")?
-}
-
-// Output: "failed to fetch user 42: connection refused"
-// All lowercase, clean chain
-```
-
-## Display vs Debug
-
-```rust
-#[derive(Error, Debug)]
-#[error("invalid configuration")]  // Display: for users/logs
-pub struct ConfigError {
-    path: PathBuf,
-    source: io::Error,
-}
-
-// Debug output (for developers) can have more detail
-// Display output (for users) should be clean
-```
-
-## When to Use Capitals
-
-```rust
-// Proper nouns / acronyms keep their case
-#[error("invalid JSON syntax")]     // JSON is an acronym
-#[error("OAuth token expired")]     // OAuth is a proper noun
-#[error("HTTP request failed")]     // HTTP is an acronym
-
-// Error codes can be uppercase
-#[error("error code E0001: invalid input")]
-```
-
-## See Also
-
-- [err-thiserror-lib](./err-thiserror-lib.md) - Error definition with thiserror
-- [err-context-chain](./err-context-chain.md) - Adding context to errors
-- [doc-examples-section](./doc-examples-section.md) - Documentation conventions

package/template/agent/skills/rust-developer/references/rust-rules/err-no-unwrap-prod.md

@@ -1,115 +0,0 @@
-# err-no-unwrap-prod
-
-> Avoid `unwrap()` in production code; use `?`, `expect()`, or handle errors
-
-## Why It Matters
-
-`unwrap()` panics on `None` or `Err` without any context about what went wrong. In production, this creates cryptic crash messages that are hard to debug. Either propagate errors with `?`, use `expect()` with a message explaining the invariant, or handle the error explicitly.
-
-## Bad
-
-```rust
-fn process_request(req: Request) -> Response {
-    let user_id = req.headers.get("X-User-Id").unwrap();  // Why did it fail?
-    let user = database.find_user(user_id).unwrap();       // Which operation?
-    let data = user.preferences.get("theme").unwrap();     // No context
-    
-    Response::new(data)
-}
-
-// Crash message: "called `Option::unwrap()` on a `None` value"
-// Where? Why? No idea.
-```
-
-## Good
-
-```rust
-// Option 1: Propagate with ?
-fn process_request(req: Request) -> Result<Response, AppError> {
-    let user_id = req.headers
-        .get("X-User-Id")
-        .ok_or(AppError::MissingHeader("X-User-Id"))?;
-    
-    let user = database.find_user(user_id)?;
-    
-    let data = user.preferences
-        .get("theme")
-        .ok_or(AppError::MissingPreference("theme"))?;
-    
-    Ok(Response::new(data))
-}
-
-// Option 2: expect() for invariants (not user input)
-fn get_config_value(&self, key: &str) -> &str {
-    self.config
-        .get(key)
-        .expect("BUG: required config key missing after validation")
-}
-
-// Option 3: Provide defaults
-fn get_theme(user: &User) -> &str {
-    user.preferences
-        .get("theme")
-        .unwrap_or(&"default")
-}
-
-// Option 4: Match for complex handling
-fn process_optional(value: Option<Data>) -> ProcessedData {
-    match value {
-        Some(data) => process(data),
-        None => {
-            log::warn!("No data provided, using fallback");
-            ProcessedData::default()
-        }
-    }
-}
-```
-
-## `expect()` vs `unwrap()`
-
-```rust
-// Bad: no context
-let port = config.get("port").unwrap();
-
-// Better: explains the invariant
-let port = config.get("port")
-    .expect("config must contain 'port' after validation");
-
-// Best: propagate if it's not truly an invariant
-let port = config.get("port")
-    .ok_or_else(|| ConfigError::MissingKey("port"))?;
-```
-
-## Alternatives to unwrap()
-
-| Situation | Use Instead |
-|-----------|-------------|
-| Can propagate error | `?` operator |
-| Has sensible default | `unwrap_or()`, `unwrap_or_default()` |
-| Default requires computation | `unwrap_or_else(\|\| ...)` |
-| Internal invariant | `expect("explanation")` |
-| Need to handle both cases | `match` or `if let` |
-
-## Clippy Lints
-
-```toml
-# Cargo.toml
-[lints.clippy]
-unwrap_used = "warn"      # Warn on unwrap()
-expect_used = "warn"       # Also warn on expect() (stricter)
-```
-
-```rust
-// Allow in specific places where it's justified
-#[allow(clippy::unwrap_used)]
-fn definitely_safe() {
-    // Unwrap is safe here because...
-    let x = Some(5).unwrap();
-}
-```
-
-## See Also
-
-- [err-result-over-panic](./err-result-over-panic.md) - Return Result instead of panicking
-- [err-expect-bugs-only](./err-expect-bugs-only.md) - When expect() is appropriate
-- [anti-unwrap-abuse](./anti-unwrap-abuse.md) - Patterns for avoiding unwrap

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