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.

Drop/Teardown Precision

• Drop lock guards before any .await -- a held MutexGuard across an await blocks the executor.
• Close stdin explicitly in Drop impls. Brief wait, then fallback kill.
• Use kill_on_drop(true) for child processes that must not outlive their parent.
• Order cleanup deterministically: clear listeners -> drain tasks -> drop resources.

Defensive Serialization

• BEGIN IMMEDIATE not BEGIN for SQLite write transactions (prevents SQLITE_BUSY_SNAPSHOT).
• Serialize lock acquisition rather than adding retries.
• ON CONFLICT DO NOTHING over read-then-write for idempotent inserts.

Orphan Event Handling

When events arrive for entities that no longer exist (dead agents, closed threads), handle explicitly. Never silently drop -- log a warning and clean up stale state. Panicking on an orphan event is always wrong.

Ownership Decision Tree

Walk this tree in order when you need shared access to data:

1. Can you pass a reference? Use &T. Zero cost, zero complexity.
2. Might it be owned or borrowed? Use Cow<'_, str>. Zero-cost when borrowed.
3. Multiple owners across sync boundaries? Use Arc<T>. Prefer Arc::clone(&x) over x.clone().
4. Multiple owners AND mutability? Use Arc<Mutex<T>> or Arc<RwLock<T>>. Choose RwLock when reads vastly outnumber writes.
5. Fire-and-forget spawn? Use move closure with owned data.

Every .clone() is a decision point. Ask: "Is this clone necessary, or can I restructure to borrow?"

Error Philosophy

Error enum design: user-facing messages tell the user what to do, not what went wrong internally. Box<T> large payloads. Classify every variant explicitly in is_retryable() -- no wildcards.

Async Decisions

When to Box::pin: When thin async wrappers inline large callee futures into their state machine, causing stack pressure. Wrap the inner call: Box::pin(self.inner_method(args)).await.

Shutdown: use CancellationToken for hierarchical shutdown. Never rely on Drop for ordered async cleanup. Never hold a MutexGuard across an .await point.

Pass 3: Simplify

Review your code as if you're trying to REMOVE things, not add them.

Three diagnostic questions:

1. Is any parameter just forwarded through a call chain? Remove it, use ambient access.
2. Is any field or function unused? Delete it.
3. Is any abstraction unjustified? (single-use helper, wrapper that adds nothing) Inline it.

"Rewrite, don't rewire" principle: When the bug is in a function's internal logic, rewrite the body with explicit checks. Don't delegate to an existing API that happens to produce the correct result for now -- the explicit version is more auditable and survives upstream changes.

If you added more code than the task strictly requires, something is wrong. Cut it.

Pass 4: Verify

Run the bundled lint script on your code:

bash ${SKILL_DIR}/scripts/lint.sh <your-file.rs>

Fix every ERROR. Review every WARNING. Then do the manual checklist:

[ ] Every ? has .context("failed to [verb] [noun]")

Fix every violation before presenting the code.

Quick Reference: The 9 Transformations

Each transformation shows the exact delta between first-draft and production-grade.

1. .context() on Every ? Operator

BEFORE:

AFTER:

Pattern: "failed to [verb] [noun]". The upstream error describes itself -- your job is to name the operation that broke.

2. Enums Over Booleans

BEFORE:

AFTER:

foo(true, false) is meaningless. Replace with enums so callsites read NetworkMode::Restricted, AccessLevel::ReadOnly. When you cannot change the API, add /*param_name*/ comments before opaque literals.

3. BTreeMap for Serialized or Compared Data

BEFORE: HashMap<String, Rule> -- AFTER: BTreeMap<String, Rule>

HashMap iteration order is random -- diffs become noisy, snapshot tests flake. Use BTreeMap whenever data is serialized, compared in tests, or shown to users.

4. Exhaustive Match Without Wildcards

BEFORE:

AFTER:

When a new variant is added, the compiler flags every match that needs updating. Wildcards hide this.

5. Return Structs Over Tuples

BEFORE: fn build_command() -> (Vec<String>, Vec<OwnedFd>) -- caller writes result.0 AFTER: fn build_command() -> CommandOutput -- caller writes output.args, output.preserved_fds

Named fields are self-documenting. Define a struct for any function returning 2+ values.

6. Default Derive on Config Structs

Derive Default so callers override only what matters. For non-zero defaults, implement Default manually.

7. Cow<str> for Conditional Ownership

BEFORE:

AFTER:

Cow<str> avoids the unconditional allocation when only some paths need to allocate.

8. Enum-as-Disjoint-Union

BEFORE:

AFTER:

When a struct has Option<T> fields valid only in certain combinations, it permits invalid states at the type level. Convert to an enum where each variant carries only its relevant data. Diagnostic: if you see 2+ Option<T> fields with is_some()/is_none() guards, it should be an enum.

9. Struct-for-Long-Parameter-Lists

BEFORE:

AFTER:

At 4+ parameters, callsites become hard to read and easy to misorder. An args struct names each field at the callsite and makes future parameter additions non-breaking.