agy-superpowers 5.2.2 → 5.2.3

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

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