agy-superpowers 5.1.4 → 5.1.6

package/template/agent/skills/rust-developer/references/rust-rules/type-option-nullable.md

@@ -0,0 +1,137 @@
+# type-option-nullable
+
+> Use `Option<T>` for values that might not exist
+
+## Why It Matters
+
+`Option<T>` explicitly represents "value or nothing" in the type system. Unlike null pointers or sentinel values, you can't accidentally use a missing value—the compiler forces you to handle the `None` case. This eliminates null pointer exceptions at compile time.
+
+## Bad
+
+```rust
+// Sentinel values - easy to forget to check
+fn find_user(id: u64) -> User {
+    // Returns "empty" user if not found - caller might not check
+    users.get(&id).cloned().unwrap_or(User::empty())
+}
+
+// Nullable-style with raw pointers
+fn find_user(id: u64) -> *const User {
+    // Null if not found - unsafe, no compiler help
+}
+
+// Error-prone usage
+let user = find_user(42);
+println!("{}", user.name);  // Might be empty user - silent bug
+```
+
+## Good
+
+```rust
+// Option makes absence explicit
+fn find_user(id: u64) -> Option<User> {
+    users.get(&id).cloned()
+}
+
+// Must handle the None case
+let user = find_user(42);
+match user {
+    Some(u) => println!("{}", u.name),
+    None => println!("User not found"),
+}
+
+// Or use combinators
+let name = find_user(42)
+    .map(|u| u.name)
+    .unwrap_or_else(|| "Unknown".to_string());
+```
+
+## Common Option Patterns
+
+```rust
+// if let for single case
+if let Some(user) = find_user(id) {
+    process(user);
+}
+
+// Chaining with map
+let upper_name = find_user(id)
+    .map(|u| u.name)
+    .map(|n| n.to_uppercase());
+
+// Providing defaults
+let user = find_user(id).unwrap_or_default();
+let user = find_user(id).unwrap_or_else(|| User::guest());
+
+// ? operator for propagation
+fn get_user_email(id: u64) -> Option<String> {
+    let user = find_user(id)?;
+    Some(user.email)
+}
+
+// and_then for chained optionals
+fn get_user_country(id: u64) -> Option<String> {
+    find_user(id)
+        .and_then(|u| u.address)
+        .and_then(|a| a.country)
+}
+```
+
+## Struct Fields
+
+```rust
+struct User {
+    name: String,
+    email: String,
+    phone: Option<String>,        // Optional field
+    avatar_url: Option<Url>,      // Optional field
+}
+
+impl User {
+    fn display_phone(&self) -> &str {
+        self.phone.as_deref().unwrap_or("Not provided")
+    }
+}
+```
+
+## Option vs Result
+
+```rust
+// Option: value might not exist (no error context)
+fn find(key: &str) -> Option<Value> { ... }
+
+// Result: operation might fail (with error context)
+fn parse(input: &str) -> Result<Value, ParseError> { ... }
+
+// Convert Option to Result
+let value = find("key").ok_or(Error::NotFound)?;
+
+// Convert Result to Option
+let value = parse("input").ok();  // Discards error
+```
+
+## Option References
+
+```rust
+// Option<&T> for optional borrows
+fn get(&self, key: &str) -> Option<&Value> {
+    self.map.get(key)
+}
+
+// as_ref() to borrow Option contents
+let opt: Option<String> = Some("hello".to_string());
+let opt_ref: Option<&String> = opt.as_ref();
+let opt_str: Option<&str> = opt.as_deref();
+
+// as_mut() for mutable borrow
+let mut opt = Some(vec![1, 2, 3]);
+if let Some(v) = opt.as_mut() {
+    v.push(4);
+}
+```
+
+## See Also
+
+- [type-result-fallible](./type-result-fallible.md) - Result for errors
+- [type-enum-states](./type-enum-states.md) - Enums for states
+- [err-no-unwrap-prod](./err-no-unwrap-prod.md) - Handling Option safely

package/template/agent/skills/rust-developer/references/rust-rules/type-phantom-marker.md

@@ -0,0 +1,188 @@
+# type-phantom-marker
+
+> Use `PhantomData` to express type relationships without runtime cost
+
+## Why It Matters
+
+Sometimes your type needs to be parameterized by a type that doesn't appear in any field—for variance, drop order, or semantic purposes. `PhantomData<T>` tells the compiler your type is "associated with" `T` without storing any `T` data. It has zero runtime cost.
+
+## Bad
+
+```rust
+// Type parameter unused - compiler error
+struct Handle<T> {
+    id: u64,
+    // Error: parameter `T` is never used
+}
+
+// Workaround with unnecessary storage
+struct Handle<T> {
+    id: u64,
+    _type: Option<T>,  // Wastes memory, requires T: Default
+}
+```
+
+## Good
+
+```rust
+use std::marker::PhantomData;
+
+struct Handle<T> {
+    id: u64,
+    _marker: PhantomData<T>,  // Zero-size, tells compiler about T
+}
+
+impl<T> Handle<T> {
+    fn new(id: u64) -> Self {
+        Handle {
+            id,
+            _marker: PhantomData,
+        }
+    }
+}
+
+// Different Handle types are incompatible
+struct User;
+struct Order;
+
+fn process_user(h: Handle<User>) { ... }
+
+let user_handle = Handle::<User>::new(1);
+let order_handle = Handle::<Order>::new(2);
+
+process_user(user_handle);   // OK
+process_user(order_handle);  // Error: expected Handle<User>, found Handle<Order>
+```
+
+## Expressing Ownership
+
+```rust
+use std::marker::PhantomData;
+
+// Owns T conceptually (like Box<T>)
+struct Container<T> {
+    ptr: *mut T,
+    _marker: PhantomData<T>,  // Acts like we own a T
+}
+
+// Drop will be called on T when Container drops
+impl<T> Drop for Container<T> {
+    fn drop(&mut self) {
+        unsafe {
+            std::ptr::drop_in_place(self.ptr);
+        }
+    }
+}
+```
+
+## Expressing Borrowing
+
+```rust
+use std::marker::PhantomData;
+
+// Borrows T for lifetime 'a
+struct Ref<'a, T> {
+    ptr: *const T,
+    _marker: PhantomData<&'a T>,  // Acts like &'a T
+}
+
+// Compiler tracks lifetime correctly
+impl<'a, T> Ref<'a, T> {
+    fn get(&self) -> &'a T {
+        unsafe { &*self.ptr }
+    }
+}
+```
+
+## Type-Level State Machine
+
+```rust
+use std::marker::PhantomData;
+
+// States as zero-size types
+struct Unlocked;
+struct Locked;
+
+struct Door<State> {
+    _state: PhantomData<State>,
+}
+
+impl Door<Unlocked> {
+    fn lock(self) -> Door<Locked> {
+        println!("Locking...");
+        Door { _state: PhantomData }
+    }
+    
+    fn open(&self) {
+        println!("Opening...");
+    }
+}
+
+impl Door<Locked> {
+    fn unlock(self) -> Door<Unlocked> {
+        println!("Unlocking...");
+        Door { _state: PhantomData }
+    }
+    
+    // Can't call open() on Locked door - method doesn't exist
+}
+
+fn example() {
+    let door: Door<Unlocked> = Door { _state: PhantomData };
+    door.open();           // OK
+    let locked = door.lock();
+    // locked.open();      // Error: no method `open` for Door<Locked>
+    let unlocked = locked.unlock();
+    unlocked.open();       // OK
+}
+```
+
+## Variance Control
+
+```rust
+use std::marker::PhantomData;
+
+// Covariant in T (PhantomData<T>)
+struct Producer<T> {
+    _marker: PhantomData<T>,  // Covariant
+}
+
+// Contravariant in T (PhantomData<fn(T)>)
+struct Consumer<T> {
+    _marker: PhantomData<fn(T)>,  // Contravariant
+}
+
+// Invariant in T (PhantomData<fn(T) -> T>)
+struct Both<T> {
+    _marker: PhantomData<fn(T) -> T>,  // Invariant
+}
+```
+
+## Common Uses
+
+```rust
+// 1. FFI handles with type safety
+struct FileHandle<T: FileType> {
+    fd: i32,
+    _marker: PhantomData<T>,
+}
+
+// 2. Generic iterators
+struct Iter<'a, T> {
+    ptr: *const T,
+    end: *const T,
+    _marker: PhantomData<&'a T>,
+}
+
+// 3. Allocator-aware types
+struct Vec<T, A: Allocator = Global> {
+    buf: RawVec<T, A>,
+    len: usize,
+}
+```
+
+## See Also
+
+- [api-typestate](./api-typestate.md) - State machine pattern
+- [api-newtype-safety](./api-newtype-safety.md) - Type-safe wrappers
+- [type-newtype-ids](./type-newtype-ids.md) - ID types

package/template/agent/skills/rust-developer/references/rust-rules/type-repr-transparent.md

@@ -0,0 +1,143 @@
+# type-repr-transparent
+
+> Use `#[repr(transparent)]` for newtypes in FFI contexts
+
+## Why It Matters
+
+`#[repr(transparent)]` guarantees a newtype has the same memory layout as its inner type. This is essential for FFI where you need type safety in Rust but must match C ABI layouts. Without it, the compiler may add padding or change layout.
+
+## Bad
+
+```rust
+// No layout guarantee - might not match inner type in FFI
+struct Handle(u64);
+
+// Passing to C code might fail
+extern "C" {
+    fn process_handle(h: Handle);  // May not work correctly
+}
+
+// Wrapping C type without layout guarantee
+struct SafePointer(*mut c_void);
+```
+
+## Good
+
+```rust
+// Guaranteed same layout as inner type
+#[repr(transparent)]
+struct Handle(u64);
+
+// Safe for FFI
+extern "C" {
+    fn process_handle(h: Handle);  // Works - same layout as u64
+}
+
+// FFI pointer wrapper
+#[repr(transparent)]
+struct SafePointer(*mut c_void);
+
+impl SafePointer {
+    // Safe Rust API around raw pointer
+    pub fn new(ptr: *mut c_void) -> Option<Self> {
+        if ptr.is_null() {
+            None
+        } else {
+            Some(SafePointer(ptr))
+        }
+    }
+}
+```
+
+## What repr(transparent) Guarantees
+
+```rust
+use std::mem::{size_of, align_of};
+
+#[repr(transparent)]
+struct Meters(f64);
+
+// Same size
+assert_eq!(size_of::<Meters>(), size_of::<f64>());
+
+// Same alignment
+assert_eq!(align_of::<Meters>(), align_of::<f64>());
+
+// Same ABI - can pass where f64 expected
+extern "C" fn measure(distance: Meters) { ... }
+```
+
+## With PhantomData
+
+```rust
+use std::marker::PhantomData;
+
+// PhantomData is zero-sized, doesn't affect layout
+#[repr(transparent)]
+struct TypedHandle<T> {
+    raw: u64,
+    _marker: PhantomData<T>,  // Zero-sized, ignored for layout
+}
+
+// Still same layout as u64
+assert_eq!(size_of::<TypedHandle<String>>(), size_of::<u64>());
+```
+
+## NonZero Wrappers
+
+```rust
+use std::num::NonZeroU64;
+
+#[repr(transparent)]
+struct NonZeroHandle(NonZeroU64);
+
+// Inherits null-pointer optimization
+assert_eq!(size_of::<Option<NonZeroHandle>>(), size_of::<u64>());
+```
+
+## FFI Pattern
+
+```rust
+mod ffi {
+    use std::os::raw::c_int;
+    
+    #[repr(transparent)]
+    pub struct FileDescriptor(c_int);
+    
+    extern "C" {
+        pub fn open(path: *const i8, flags: c_int) -> FileDescriptor;
+        pub fn close(fd: FileDescriptor) -> c_int;
+        pub fn read(fd: FileDescriptor, buf: *mut u8, len: usize) -> isize;
+    }
+}
+
+// Safe wrapper
+pub struct File {
+    fd: ffi::FileDescriptor,
+}
+
+impl File {
+    pub fn open(path: &str) -> std::io::Result<Self> {
+        let c_path = std::ffi::CString::new(path)?;
+        let fd = unsafe { ffi::open(c_path.as_ptr(), 0) };
+        // ... error handling
+        Ok(File { fd })
+    }
+}
+```
+
+## When to Use
+
+| Scenario | Use `#[repr(transparent)]`? |
+|----------|----------------------------|
+| FFI newtype wrappers | Yes |
+| Type-safe handles | Yes |
+| NonZero optimization | Yes |
+| Pure Rust newtypes | Optional (doesn't hurt) |
+| Multi-field structs | N/A (only for single-field) |
+
+## See Also
+
+- [type-newtype-ids](./type-newtype-ids.md) - Newtype pattern
+- [type-phantom-marker](./type-phantom-marker.md) - PhantomData usage
+- [api-newtype-safety](./api-newtype-safety.md) - Type-safe newtypes

package/template/agent/skills/rust-developer/references/rust-rules/type-result-fallible.md

@@ -0,0 +1,131 @@
+# type-result-fallible
+
+> Use `Result<T, E>` for operations that can fail
+
+## Why It Matters
+
+`Result<T, E>` makes failure explicit in the type system. Callers must acknowledge and handle potential errors—they can't accidentally ignore failures. The `?` operator makes error propagation ergonomic while maintaining explicit error handling.
+
+## Bad
+
+```rust
+// Returning Option loses error context
+fn read_config(path: &str) -> Option<Config> {
+    let content = std::fs::read_to_string(path).ok()?;  // Why did it fail?
+    toml::from_str(&content).ok()  // Parse error lost
+}
+
+// Panicking on errors
+fn read_config(path: &str) -> Config {
+    let content = std::fs::read_to_string(path).unwrap();  // Crashes
+    toml::from_str(&content).unwrap()  // Crashes
+}
+
+// Sentinel values
+fn divide(a: i32, b: i32) -> i32 {
+    if b == 0 { return -1; }  // Magic value, easy to miss
+    a / b
+}
+```
+
+## Good
+
+```rust
+// Result with clear error type
+fn read_config(path: &str) -> Result<Config, ConfigError> {
+    let content = std::fs::read_to_string(path)
+        .map_err(ConfigError::IoError)?;
+    toml::from_str(&content)
+        .map_err(ConfigError::ParseError)
+}
+
+fn divide(a: i32, b: i32) -> Result<i32, DivisionError> {
+    if b == 0 {
+        return Err(DivisionError::DivideByZero);
+    }
+    Ok(a / b)
+}
+
+// Caller must handle
+match divide(10, 0) {
+    Ok(result) => println!("Result: {}", result),
+    Err(e) => println!("Error: {}", e),
+}
+```
+
+## The ? Operator
+
+```rust
+fn process_file(path: &str) -> Result<ProcessedData, Error> {
+    let content = std::fs::read_to_string(path)?;  // Propagates Err
+    let parsed: RawData = serde_json::from_str(&content)?;
+    let validated = validate(parsed)?;
+    let processed = transform(validated)?;
+    Ok(processed)
+}
+
+// Equivalent to:
+fn process_file(path: &str) -> Result<ProcessedData, Error> {
+    let content = match std::fs::read_to_string(path) {
+        Ok(c) => c,
+        Err(e) => return Err(e.into()),
+    };
+    // ... etc
+}
+```
+
+## Result Combinators
+
+```rust
+let result: Result<i32, Error> = Ok(42);
+
+// map: transform success value
+let doubled = result.map(|n| n * 2);  // Ok(84)
+
+// map_err: transform error
+let with_context = result.map_err(|e| format!("Failed: {}", e));
+
+// and_then: chain fallible operations
+let processed = result.and_then(|n| {
+    if n > 0 { Ok(n * 2) } else { Err(Error::Negative) }
+});
+
+// unwrap_or: provide default on error
+let value = result.unwrap_or(0);
+
+// ok(): convert to Option, discarding error
+let maybe_value: Option<i32> = result.ok();
+```
+
+## Defining Error Types
+
+```rust
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum ConfigError {
+    #[error("failed to read file: {0}")]
+    Io(#[from] std::io::Error),
+    
+    #[error("failed to parse config: {0}")]
+    Parse(#[from] toml::de::Error),
+    
+    #[error("missing required field: {0}")]
+    MissingField(String),
+}
+
+fn load_config(path: &str) -> Result<Config, ConfigError> {
+    let content = std::fs::read_to_string(path)?;  // Io error
+    let config: Config = toml::from_str(&content)?;  // Parse error
+    if config.name.is_empty() {
+        return Err(ConfigError::MissingField("name".into()));
+    }
+    Ok(config)
+}
+```
+
+## See Also
+
+- [err-thiserror-lib](./err-thiserror-lib.md) - Defining error types
+- [err-question-mark](./err-question-mark.md) - Using ? operator
+- [type-option-nullable](./type-option-nullable.md) - Option vs Result

package/template/agent/skills/systematic-debugging/SKILL.md

@@ -167,6 +167,23 @@ You MUST complete each phase before proceeding to the next.
    - Ask for help
    - Research more
 
+### Confirmation Gate: Present Analysis Before Fixing
+
+<HARD-GATE>
+You MUST present your complete analysis to the user and get explicit confirmation
+BEFORE proceeding to Phase 4 (Implementation).
+
+**Present a summary containing:**
+1. **Root Cause** — from Phase 1
+2. **Pattern Analysis** — key differences found in Phase 2
+3. **Hypothesis** — your confirmed theory from Phase 3
+4. **Proposed Fix** — what you plan to change (files, functions, approach)
+
+Then ask: "Bạn đồng ý với phân tích và hướng fix này không?"
+
+Wait for user confirmation. Do NOT proceed to Phase 4 until confirmed.
+</HARD-GATE>
+
 ### Phase 4: Implementation
 
 **Fix the root cause, not the symptom:**