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

* refactor(parsed_value): remove unnecessary `Error` derive

`ParsedValue` is not an error type — it's a display wrapper for
formatted byte values. Remove the unused `Error` derive and update
documentation to clarify that `Display` and `Error` should only be
derived when actually used.

https://claude.ai/code/session_012YdPMpQ3UiSmqFSU2vUULm

* docs: clarify when to derive `Display` and `Error` from `derive_more`

Update CONTRIBUTING.md and AI instruction templates to clarify that
`Display` and `Error` should only be derived when each trait is actually
used, rather than always bundling them together as `#[derive(Debug,
Display, Error)]`.

https://claude.ai/code/session_012YdPMpQ3UiSmqFSU2vUULm

* docs: fix misleading claim about Error not needing Display

`std::error::Error` requires `Display` as a supertrait, so saying "not
all error types need Display" was inaccurate. Simplify the guideline to
focus on the valid point: not all displayable types are errors.

https://claude.ai/code/session_012YdPMpQ3UiSmqFSU2vUULm

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: KSXGitHub

.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. If a test fails with a hint about `RUSTFLAGS` and `--cfg pdu_test_skip_*`, follow the hint and rerun with the suggested flags.

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. If a test fails with a hint about `RUSTFLAGS` and `--cfg pdu_test_skip_*`, follow the hint and rerun with the suggested flags.

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. If a test fails with a hint about `RUSTFLAGS` and `--cfg pdu_test_skip_*`, follow the hint and rerun with the suggested flags.

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. If a test fails with a hint about `RUSTFLAGS` and `--cfg pdu_test_skip_*`, follow the hint and rerun with the suggested flags.