rust-implement

Files (4)

• AGENTS.md
• SKILL.md
• metadata.json
• lint.sh · scripts/

SKILL.md (first lines)

# 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

| Context | Tool | Why |
|---------|------|-----|
| Application code (main, CLI, tests) | `anyhow::Result` + `.context()` | Rich error chains, no boilerplate |
| Library code (crates consumed by others) | `thiserror` enums | Typed, matchable, callers can branch on variants |

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`.

| Need | Channel | Why |
|------|---------|-----|
| One response back | `oneshot` | Exactly one value, then done |
| Stream of events | `mpsc` | Multiple producers, single consumer |
| Latest value only | `watch` | Receivers always see the most recent value |
| Broadcast to all | `broadcast` | Every receiver gets every message |

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
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]")

From pproenca/dot-skills, MIT.

More from pproenca/dot-skills