hayatosc/dotfiles/rust-best-practices

Rust Design Decisions

Scope

Apply this skill to decisions where multiple Rust designs compile but differ in soundness, cancellation behavior, compatibility, operational cost, or proof burden. Do not spend output on elementary ownership rules, Option versus Result, routine formatting, or other defaults unless they are the cause of the specific failure.

Decision Protocol

1. Read stumbling-blocks.md when starting from a compiler error, workaround, or vague design discomfort. Diagnose the architectural pressure before changing syntax.
2. Write down the contracts that matter:

• invariant and trust boundary;
• owner and lifetime of each resource;
• failure, cancellation, and cleanup semantics;
• public API, MSRV, feature, layout, documentation, and trait commitments;
• measured performance constraint.

1. Separate reversible choices from commitments. A private allocation strategy is reversible; a public trait implementation, error variant, feature, auto-trait result, layout, or callback contract may not be.
2. Compare viable designs by proof burden and failure mode, not line count. Prefer the weakest mechanism that expresses the contract: scoped ownership before shared ownership, safe abstraction before unsafe, concrete type before dynamic dispatch, and private policy before public commitment.
3. Test the disputed contract directly. Compilation alone does not establish cancellation safety, panic safety, feature composability, FFI validity, doc-test execution, or unsafe soundness.

Evidence Discipline

Treat advice according to its evidence level:

1. Language/library guarantees and documented runtime behavior establish what is sound or supported.
2. Repeated production and community failure reports reveal where correct-looking designs are routinely misunderstood.
3. Personal preferences, crate choices, lint sets, allocator choices, numeric thresholds, and architecture slogans are hypotheses until the repository's constraints or measurements support them.

When community advice conflicts, preserve the decision variables instead of manufacturing a universal rule. Read community-practice.md for recurring field lessons and the agent skills reviewed while building this skill.

Signals to Reconsider the Design

Do not paper over the following signals:

• repeated clone, Arc, 'static, Box::leak, or Box::pin solely to satisfy the compiler;
• a lock guard, transaction, partially initialized buffer, or external handle surviving a suspension or callback;
• an unsafe comment that depends on undocumented caller behavior behind a safe API;
• a public API change reviewed only at the source-signature level;
• mutually exclusive Cargo features or a feature that disables behavior;
• optimization justified without a representative profile or benchmark;
• detached tasks whose completion, errors, or shutdown behavior are unobserved.

At these signals, return to the ownership, state-machine, API, or safety boundary and continue resolving the requested design. Stop only for a concrete blocker or when the affected contract is established.

Reference Routing

Read only the references needed for the decision:

• Symptom-driven diagnosis and common expert traps: stumbling-blocks.md
• Community field lessons, disputed heuristics, and lessons from other Rust agent skills: community-practice.md
• Ownership topology, self-reference, lifetimes, pinning, and trait coherence: core-idioms.md
• Public API evolution, traits, dynamic dispatch, errors, and SemVer: api-design.md
• Documentation comments, intra-doc links, doc tests, section standards, and lint enforcement: documentation.md
• Failure taxonomy, partial effects, retries, cleanup, and panic boundaries: error-handling.md
• Task ownership, cancellation, backpressure, locks, and blocking work: concurrency-async.md
• Risk-directed testing, model checking, fuzzing, and unsafe verification: testing.md
• Measurement-led choices around allocation, dispatch, layout, and unsafe optimization: performance.md
• Unsafe proof design, MaybeUninit, provenance, FFI, pinning, and Send/Sync: unsafe-security.md
• Feature topology, MSRV, resolver behavior, dependency exposure, and CI matrices: cargo-tooling.md

Review Order

1. Soundness, validity, aliasing, provenance, data races, ABI, and unwind boundaries.
2. Lost work, partial effects, cancellation, cleanup, deadlocks, and resource lifetime.
3. Public compatibility and contracts: downstream implementations, inference, doc comments (//////!) with # Safety/# Errors/# Panics, intra-doc links, runnable doc tests using ?, feature combinations, MSRV, layout, and auto traits.
4. Ownership topology and operability: backpressure, observability, shutdown, and error context.
5. Measured performance and compile-cost tradeoffs.

Report a concrete failure scenario and the violated contract. Label optional simplifications separately from correctness or compatibility defects.