craft

Systematic fix loop for review findings — gather them from craft review agents, rust-audit reports, and GitHub PR comments, triage each against the code, order, fix, verify, and re-review until green. Use after a review or audit produces findings, working through PR comments, or deciding what to fix first. Triggers: address review comments, fix the findings, triage findings, what to fix first.

Quickly understand an unfamiliar codebase before changing it — map the structure, find entry points and seams, trace one real flow end to end, and confirm by building/testing. Use when dropped into a new or large repo, or before changing code you don't know. Language-agnostic. Triggers: where do I start, how does this work, trace the flow, get oriented, onboard.

Rust debugging toolbox — reproducing, localizing, and explaining a bug (minimal repro, git bisect / cargo bisect-rustc, dbg!/tracing/RUST_BACKTRACE, Miri/loom for heisenbugs, rust-gdb/rr). Use for any Rust bug, panic, test failure, crash, or flaky behavior. Triggers: bisect, cargo bisect-rustc, heisenbug, RUST_BACKTRACE, loom, rr, why is this failing.

Nix dev shells — mkShell, devShells.default, direnv with use flake, writeShellApplication for lint-checked scripts, formatters (alejandra, nixpkgs-fmt), linters (statix, deadnix), and pre-commit-hooks.nix. Use when building or debugging a dev environment in a flake, wiring direnv, or setting up Nix quality gates. Triggers: devShell, mkShell, direnv, .envrc, writeShellApplication, alejandra, statix, deadnix, pre-commit.

Nix flakes — flake.nix inputs/outputs schema, pinning with flake.lock, the standard outputs (devShells, packages, nixosConfigurations, homeConfigurations), and flake-parts / flake-utils. Use when writing or debugging a flake, pinning or updating inputs, or exposing dev shells or packages. Triggers: flake.nix, flake.lock, nix flake, inputs, outputs, flake-parts, follows.

Nix derivations — stdenv.mkDerivation and the phase model, fixed-output hashes for src fetchers, language-builder dependency hashes (cargoHash, vendorHash, npmDepsHash), the lib.fakeHash → copy-real-hash workflow, and meta attributes. Use when writing, debugging, or reviewing a derivation, packaging a Rust/Go/Python/Node project, or fixing a hash mismatch. Triggers: mkDerivation, buildRustPackage, buildGoModule, vendorHash, cargoHash, fetchFromGitHub.

Nix code-review rubric — the flake quality gate (nix flake check, formatter --check, statix, deadnix, nix build/eval), a severity-tiered checklist (purity, reproducibility, injection, packaging, dev-env, modules), the Approve/Warning/Block verdict (and INCOMPLETE when nix and the linters are all unavailable, so the gate never ran), and the "what proves what" table. Use when reviewing Nix code or a flake, checking for impure derivations or IFD, or deciding if a change is mergeable. Triggers: nix review, review flake, statix, deadnix, nix flake check, impure derivation, IFD.

NixOS and nix-darwin system configuration — module shape, typed options with lib.mkOption, composing modules, nixosConfigurations, secrets (agenix/sops-nix), and cross-platform via nix-darwin + Home Manager. Use when writing a system module or config. Triggers: nixosConfiguration, nixos module, home-manager, nix-darwin, agenix, sops-nix, systemd service.

Disciplined refactoring — change structure without changing behavior, in tiny reversible steps under green tests. Use when restructuring code, paying down a smell, or preparing messy code for a change. Language-agnostic. Triggers: refactor, code smell, technical debt, extract function, make this testable.

Hexagonal architecture (ports and adapters) in Rust — a domain core that depends on nothing, ports as traits, adapters at the edges, one-way dependency flow toward the domain. Use when structuring an app/service, isolating business logic from frameworks, deciding module layout, or making code testable without infrastructure. Triggers: ports and adapters, clean architecture, dependency inversion, repository pattern, where does this code go.

Rust architecture-audit rubric — builds a whole-project dependency graph (crates and modules), then judges it against a checklist (cycles, inverted dependencies, layer leaks, god modules, anemic domain) and over-engineering (ghost abstractions, over-layering), issuing a Healthy/Concerns/At-risk rating — and INCOMPLETE (not run) when no graph could be built at all, never Healthy. Use when auditing a Rust project's architecture or structural debt. Triggers: structural debt, dependency cycle, layer leak, god module, is this over-engineered.

Command-line and terminal apps in Rust — argument parsing with clap, subcommands, config, output/exit-code conventions, and full-screen TUIs with ratatui. Use when building a CLI, parsing args/subcommands, designing output, or writing a terminal UI. Triggers: clap, subcommand, exit code, TUI, ratatui, crossterm, indicatif.

Cloud-native Rust services — gRPC with tonic, observability (tracing + OpenTelemetry), health/readiness probes, 12-factor config, graceful shutdown, and lean containers. Use when building microservices or gRPC APIs, running in Docker/Kubernetes, or adding tracing/metrics/health checks. Triggers: gRPC, tonic, opentelemetry, OTLP, readiness, 12-factor, distroless.

Rust concurrency and async — threads vs async, Send/Sync, sharing with Arc/Mutex/RwLock, channels, tokio tasks, holding locks across await, and deadlocks. Use when parallelizing work, sharing state across threads, choosing threads vs async, or fixing Send/Sync errors and deadlocks. Triggers: tokio, Send/Sync, mpsc, deadlock, future is not Send, rayon, parking_lot.

Rust ecosystem and project setup — choosing crates, Cargo.toml and dependencies, features, workspaces, editions/MSRV, module layout, and publishing libraries. Use when adding a dependency, structuring a project or workspace, configuring Cargo, or preparing a crate to publish. Triggers: Cargo.toml, cargo add, feature flag, workspace, edition, MSRV, semver, which crate.

Bare-metal / microcontroller Rust (no_std firmware) — the constraints (no heap, interrupts, real-time deadlines, single-instance peripherals) and the patterns that satisfy them: heapless collections, peripheral singletons, embedded-hal drivers, ISR-safe critical sections, and RTIC vs Embassy. Use when writing firmware for Cortex-M / RISC-V / ESP or picking an MCU concurrency model. Triggers: no_std, cortex-m, esp32, stm32, rp2040, embedded-hal, RTIC, embassy, heapless, defmt, probe-rs.

Rust error handling — Result vs Option vs panic, the ? operator, thiserror for libraries vs anyhow for applications, error design, context, and recovery (retry, fallback, circuit breaker). Use when designing or fixing error handling, choosing an error type/crate, propagating errors, or making code resilient. Triggers: ?, thiserror, anyhow, error propagation, retry, circuit breaker, E0277.

Financial/money code in Rust — exact decimal arithmetic (never floats), a Money type with currency, rounding modes, splitting without losing cents, idempotency, and double-entry ledgers. Use when handling money, prices, currencies, payments, or accounting, where rounding and exactness are correctness-critical. Triggers: decimal, rust_decimal, banker's rounding, idempotency, ledger, double-entry.

Idiomatic Rust — naming conventions, the constructs that read as native Rust, clippy/rustfmt as enforcers, and a catalog of common anti-patterns. Use when writing or polishing Rust to be idiomatic, naming things, deciding "is this the Rust way?", or reviewing for code smells. Triggers: clippy, rustfmt, is this idiomatic, the Rust way, stringly typed, missing_docs.

Rust metaprogramming — declarative macros (macro_rules!) and procedural macros (derive, attribute, function-like) with syn/quote, plus when a macro is the wrong tool. Use when writing or debugging a macro, generating boilerplate, building a derive, or deciding macro vs generics. Triggers: macro_rules!, proc macro, derive macro, syn, quote, cargo expand.

Machine learning and numerical computing in Rust — tensors, framework choice (candle/burn/tch/ort/linfa), dtypes and determinism, avoiding needless copies of large tensors, GPU management, and serving a model without blocking the async runtime. Use for inference or training, loading a model (safetensors/ONNX), tokenizing, a data pipeline (polars/arrow), or deploying behind an API. Triggers: candle, burn, tch, ort, ONNX, ndarray, polars, safetensors, inference, GPU, spawn_blocking.

Navigate a Rust codebase with rust-analyzer over LSP instead of grepping blindly — go to definition, find references (impact before a rename), read a symbol's type/docs, find a trait's implementors, and trace a call hierarchy. Use when exploring an unfamiliar crate, locating a symbol, or assessing a change's blast radius. Triggers: where is X defined, who calls, find references, find implementations, call hierarchy, rust-analyzer, LSP.

Rust ownership, borrowing, lifetimes, and smart pointers — the mental model plus concrete fixes for borrow-checker errors. Use when fighting the borrow checker, deciding between T / &T / &mut T, choosing Box/Rc/RefCell/Cow, returning references, writing an RAII/scope guard, or lazily initializing a value. Triggers: borrow checker, cannot borrow, does not live long enough, Rc, RefCell, Cow, RAII, OnceLock, E0382, E0499, E0515, E0597, E0716.

Rust performance — measure-first methodology, benchmarking (criterion/divan), profiling, concrete optimizations (build config, allocations, hashing, type sizes, iterators), and cutting compile times. Use when code is slow, optimizing a hot path, choosing a profiler, or when builds are slow. Triggers: criterion, divan, flamegraph, FxHashMap, LTO, PGO, jemalloc, dhat, compile times, mold, sccache.

Plugin and extensibility systems in Rust — compile-time trait objects, embedded scripting, out-of-process RPC, WebAssembly, and dynamic C-ABI libraries, driven by the trust boundary. Use when designing extensibility, loading third-party code at runtime, supporting user-defined functions, or picking a plugin mechanism. Triggers: cdylib, dlopen, abi_stable, wasm plugin, wasmtime, extism, rhai, UDF.

Rust code-review rubric — the cargo quality gate, a severity-tiered checklist (safety, error handling, ownership, concurrency, performance, API quality), a public-API pass against the Rust API Guidelines, the Approve/Warning/Block verdict (and INCOMPLETE when the gate could not run at all), and how to dispatch the craft review agents. Use when reviewing Rust code or a diff, deciding if it's mergeable, or reviewing a public API. Triggers: code review, is this mergeable, dispatch reviewer, public API, what proves done.

Rust security review — dependencies for known vulnerabilities (cargo-audit/RUSTSEC), licenses and supply chain (cargo-deny), unsafe surface (cargo-geiger), and code patterns (semgrep). Use when security-reviewing a Rust project, vetting dependencies, checking for vulnerable crates or license issues, or setting up a security gate. Triggers: CVE, RUSTSEC, cargo-audit, cargo-deny, cargo-geiger, semgrep.

Rust testing — unit, integration, async, table-driven (rstest), property-based (proptest), fuzzing (cargo-fuzz), mutation (cargo-mutants), mocking (mockall), snapshot (insta), doc tests, and coverage. Use when writing or reviewing Rust tests, adding coverage, choosing a testing crate, or setting up CI. Triggers: #[tokio::test], rstest, proptest, cargo-fuzz, cargo-mutants, mockall, insta, nextest.

Rust traits, generics, and dispatch — trait bounds, impl Trait, static vs dynamic vs enum dispatch, object safety, and type-driven design (newtype, typestate, PhantomData, sealed traits). Use when designing an abstraction, choosing generics vs dyn vs enum, fixing trait-bound errors, or encoding invariants in the type system. Triggers: impl Trait, dyn, enum dispatch, object safety, newtype, typestate, PhantomData, E0277, E0038, E0119.

Unsafe Rust done soundly — what unsafe does and doesn't unlock, the SAFETY-comment discipline, undefined behavior to avoid, raw pointers, FFI, #[repr], and verifying with Miri. Use when writing or reviewing unsafe code, doing FFI, building a structure the borrow checker can't express, or chasing UB. Triggers: *mut, extern "C", #[repr(C)], SAFETY, UB, transmute, MaybeUninit, miri.

Web services in Rust with axum, tokio, tower, and sqlx — routing, extractors, shared state, error responses, database access, middleware, and graceful shutdown. Use when building an HTTP API/server, wiring axum handlers, sharing state, returning typed errors, or connecting a database. Triggers: axum, extractor, State, IntoResponse, tower, tower-http, sqlx, CORS.

Specification by example / BDD / ATDD — turning requirements into concrete Given/When/Then scenarios that double as acceptance tests, driven outside-in. Language-agnostic. Use when turning a feature, user story, or vague requirement into testable behavior before coding, or clarifying acceptance criteria. Triggers: specification by example, acceptance criteria, ATDD, BDD, given when then, gherkin, outside-in.