docs(guide/dev): refine error handling guidelines for derive_more traits

.github/copilot-instructions.md

@@ -12,7 +12,7 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c
 - Use `pipe-trait` for chaining through unary functions (constructors, `Some`, `Ok`, free functions, etc.), avoiding nested calls, and continuing method chains — but not for simple standalone calls (prefer `foo(value)` over `value.pipe(foo)`)
 - Prefer `where` clauses for multiple trait bounds
 - Derive order: std traits → comparison traits → `Hash` → derive_more → feature-gated
-- Custom errors: `#[derive(Debug, Display, Error)]`
+- Error types: only derive `Display` and `Error` from `derive_more` when each is actually needed — not all displayable types are errors
 - Minimize `unwrap()` in non-test code — use proper error handling
 - Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add --toolchain "$(< rust-toolchain)" rustfmt clippy`
 - Run `FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh` to validate changes

AGENTS.md

@@ -12,7 +12,7 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c
 - Use `pipe-trait` for chaining through unary functions (constructors, `Some`, `Ok`, free functions, etc.), avoiding nested calls, and continuing method chains — but not for simple standalone calls (prefer `foo(value)` over `value.pipe(foo)`)
 - Prefer `where` clauses for multiple trait bounds
 - Derive order: std traits → comparison traits → `Hash` → derive_more → feature-gated
-- Custom errors: `#[derive(Debug, Display, Error)]`
+- Error types: only derive `Display` and `Error` from `derive_more` when each is actually needed — not all displayable types are errors
 - Minimize `unwrap()` in non-test code — use proper error handling
 - Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add --toolchain "$(< rust-toolchain)" rustfmt clippy`
 - Run `FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh` to validate changes

CLAUDE.md

@@ -12,7 +12,7 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c
 - Use `pipe-trait` for chaining through unary functions (constructors, `Some`, `Ok`, free functions, etc.), avoiding nested calls, and continuing method chains — but not for simple standalone calls (prefer `foo(value)` over `value.pipe(foo)`)
 - Prefer `where` clauses for multiple trait bounds
 - Derive order: std traits → comparison traits → `Hash` → derive_more → feature-gated
-- Custom errors: `#[derive(Debug, Display, Error)]`
+- Error types: only derive `Display` and `Error` from `derive_more` when each is actually needed — not all displayable types are errors
 - Minimize `unwrap()` in non-test code — use proper error handling
 - Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add --toolchain "$(< rust-toolchain)" rustfmt clippy`
 - Run `FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh` to validate changes

CONTRIBUTING.md

@@ -198,7 +198,10 @@ where
 
 ### Error Handling
 
-- Define custom error enums with `#[derive(Debug, Display, Error)]` from `derive_more`.
+- Use `derive_more` for error types. Only derive the traits that are actually used:
+  - `Display`: derive when the type needs to be displayed (e.g., printed to stderr, used in format strings).
+  - `Error`: derive when the type is used as a `std::error::Error` (e.g., as the error type in `Result`, or as a source of another error). Not all types with `Display` need `Error`.
+  - A type that only needs formatting (not error handling) should derive `Display` without `Error`.
 - Minimize `unwrap()` in non-test code — use proper error propagation. `unwrap()` is acceptable in tests and for provably infallible operations (with a comment explaining why). When deliberately ignoring an error, use `.ok()` with a comment explaining why.
 
 ```rust

template/ai-instructions/shared.md

@@ -12,7 +12,7 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c
 - Use `pipe-trait` for chaining through unary functions (constructors, `Some`, `Ok`, free functions, etc.), avoiding nested calls, and continuing method chains — but not for simple standalone calls (prefer `foo(value)` over `value.pipe(foo)`)
 - Prefer `where` clauses for multiple trait bounds
 - Derive order: std traits → comparison traits → `Hash` → derive_more → feature-gated
-- Custom errors: `#[derive(Debug, Display, Error)]`
+- Error types: only derive `Display` and `Error` from `derive_more` when each is actually needed — not all displayable types are errors
 - Minimize `unwrap()` in non-test code — use proper error handling
 - Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add --toolchain "$(< rust-toolchain)" rustfmt clippy`
 - Run `FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh` to validate changes