rust-implement

Rust Implementation Discipline

Write code in passes. Experts don't produce perfect code in one shot -- they design, implement, review, and simplify. Follow this process for every module you write.

---

Pass 1: Design Types and Signatures

Before writing any implementation, write ONLY the type definitions and function signatures. No bodies. No logic.

Ask yourself these questions before moving on:

• Can any enum state represent an invalid combination? If yes, restructure so invalid states are unrepresentable.
• Are all parameters self-documenting? Replace bool params with enums (Transformation 2).
• Does every struct that will be serialized or compared use BTreeMap, not HashMap (Transformation 3)?
• Do config structs derive Default (Transformation 6)?
• Would a caller confuse the order of String parameters? Use newtypes.
• Does any struct have 2+ Option<T> fields where only one combination is valid at a time? Convert to an enum (Transformation 8).
• Does any function take 4+ parameters? Replace with an args struct (Transformation 9).

Do not proceed to Pass 2 until the types are right. Types are the architecture.

---

Pass 2: Implement

Fill in the function bodies. As you write each function, apply these rules:

• Every ? gets .context("failed to [verb] [noun]") -- no exceptions (Transformation 1).
• For library code: use thiserror for error enums. For application code: use anyhow.
• Use Cow<str> when a function sometimes borrows and sometimes allocates (Transformation 7).
• Return named structs, not tuples, from any function with 2+ return values (Transformation 5).
• Exhaustive match arms -- no _ => wildcards (Transformation 4).

Thread-Through Plumbing

When adding a new field that needs to reach execution sites, trace the full path and explicitly name every intermediate layer before writing code. For each hop, state the module and struct/function that carries the value. If you skip a layer, the field silently disappears at runtime.