Require remedy clauses in error messages where a documented fix exists; document the TensorTrainError name collision

[shinaoka]

Problem

A 2026-08-04 sweep of the 165 #[error(...)] messages across the 28 public error enums found excellent structured diagnostics (named fields, real numbers interpolated) but only ~7 messages (~4%) that tell the caller what to change. For both humans and coding agents, the error string is the primary self-correction input; a remedy clause converts a failed run into a one-step fix.

The house-style exemplar already exists, crates/tensor4all-tcicore/src/cached_function/error.rs:12:

"Cache key overflow: {total_bits} bits required, but {key_type} supports only {max_bits} bits. Use CachedFunction::with_key_type::() to specify a larger key type."

Diagnostic-only examples where a documented remedy exists but is not named:

• crates/tensor4all-simplett/src/error.rs: "Tensor train does not have a well-defined orthogonality center (ortho_lims = {start}..{end})" — never names canonicalize.
• crates/tensor4all-core/src/defaults/svd.rs: "Failed to converge after {sweeps} sweeps (final error: {error})" — never suggests raising sweeps or loosening rtol.
• crates/tensor4all-tcicore/src/error.rs:100: "Rank-deficient matrix is not supported for this operation".
• A large family degrades to opaque {message}: String payloads ("Invalid tensor structure: {message}", "Dimension mismatch: {message}"), losing the structured-field advantage.

Separate but related trap: TensorTrainError is defined twice with different variants (crates/tensor4all-simplett/src/error.rs:31 and crates/tensor4all-itensorlike/src/error.rs:10). Nothing documents the collision; a user mixing both crates gets confusing import errors.

Proposed direction

1. Adopt the rule (REPOSITORY_RULES.md, or by reference once Add shared rules for agent consumers of tensor4all libraries (rules/common/agent-consumers.md) tensor4all-agent-rules#7 lands): when a documented remediation exists (an alternative API, an option, a valid-domain list), the message names it: "; ".
2. Apply first to the highest-traffic families: orthogonality/canonicalization errors, convergence failures (name the option to adjust), and the {message}: String family (promote recurring cases to structured variants with remedies).
3. Document the TensorTrainError name collision in both crates' rustdoc (one sentence each pointing at the other), or rename one if cheap.

Reference implementation: tensor4all/tenferro-rs#1611, closed by tensor4all/tenferro-rs#1634 (actionable remedy clauses).

Non-goals

Changing error enum structure or public API; machine-readable error codes.

Acceptance criteria

• The remedy-clause rule is recorded and cited in review.
• The families in (2) carry remedy clauses; tests updated.
• The TensorTrainError collision is documented (or resolved).

[shinaoka]

Resolved by PR #593/#595/#599 (issue #566 remediation).

• Remedy documentation: # Remedies rustdoc added to the primary public error types (TensorDynLenError, BackendLinalgError, BridgeError, TreeTNOperationError, TreeTciError, QuanticsTCIError, QuanticsTransformError, Hdf5Error) in PR3: typed errors, layering, and test hygiene (issue #566) #593/PR3: API vocabulary, stack seam, and architecture (issue #566) #595.
• TensorTrainError name collision: both tensor4all-simplett::TensorTrainError and tensor4all-itensorlike::TensorTrainError now carry a cross-reference note with hosted-rustdoc links (intra-doc links cannot resolve across crate boundaries) in PR Resolve related issue #583/#578/#580/#573/#551/#588 acceptance criteria #599.

Acceptance criteria met; closing.