agy-superpowers 5.1.4 → 5.1.6

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

@@ -0,0 +1,145 @@
+# 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

@@ -0,0 +1,133 @@
+# 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

@@ -0,0 +1,152 @@
+# 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

@@ -0,0 +1,124 @@
+# 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

@@ -0,0 +1,115 @@
+# 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