Non-negotiable rules:

1. Identify the subsystem before coding. Load only the relevant references.
2. Safe Rust by default. unsafe only when justified — every unsafe block gets a // SAFETY: comment.
3. Zero-copy where possible. mmap'd segments, &str/&[u8] references into pages. Never copy data without reason.
4. Error types per crate. thiserror enums in library crates. Never anyhow in libraries — only in binaries/tests.
5. Async with tokio. All I/O is async. CPU-bound work on spawn_blocking. Never block the tokio runtime.
6. Workspace crate structure. One crate per subsystem. Depend downward — never circular.
7. Property tests for invariants. proptest for round-trips, type coercion, binary parsing.

rust

Inputs

• $request: The crate, subsystem, bug, feature, or review target

Goal

Route Rust work through the right subsystem conventions so changes follow the workspace’s systems-programming patterns instead of generic Rust defaults.

Step 0: Identify the subsystem

Decide which part of the Rust surface the task touches:

• storage engine
• binary formats
• type system
• Arrow or DataFusion
• wire protocols
• search or vectors
• arena or graph code
• geo indexing
• async or concurrency
• testing
• unsafe or error design

Success criteria: The task is mapped to the right subsystem before references are loaded.

Step 1: Load only the relevant references

Use the routing table to pick the matching files. Do not bulk-load the full reference tree.

Task / Area	Read
Toolchain, workspace layout, key crates, Cargo conventions	references/stack.md
WAL, mmap, segments, MVCC, compaction, io_uring, backends	references/storage-engine.md
Custom on-disk formats, zero-copy parsing, packed structs	references/binary-formats.md
Database type system, disk/exec types, Arrow interop	references/type-system.md
DataFusion table providers, UDFs, Arrow RecordBatch, planning	references/datafusion-arrow.md
pgwire server, MySQL protocol, dialect mapping, ORM compat	references/wire-protocols.md
tantivy FTS, HNSW vectors, SIMD distance, hybrid search	references/search-vector.md
bumpalo arenas, graph adjacency, traversal algorithms	references/arena-graph.md
R-tree spatial index, geo predicates, WGS84 distance	references/geo-rtree.md
tokio async, io_uring, crossbeam, lock-free structures, MVCC	references/async-concurrency.md
proptest, deterministic testing, integration test patterns	references/testing.md
thiserror hierarchies, unsafe patterns, safety invariants	references/error-unsafe.md

Multiple tasks? Read multiple files.

Success criteria: Only the subsystem-relevant Rust guidance is active.

Step 2: Implement with the core Rust guardrails

Keep these rules active:

• safe Rust by default; unsafe only when justified with // SAFETY:
• error types match crate boundaries (thiserror in libs, anyhow only in bins/tests)
• async code does not block the runtime; CPU work on spawn_blocking
• owned vs borrowed data choices are deliberate; prefer &[u8] over Vec<u8> in signatures
• explicit use imports — no glob imports except in test modules
• #[must_use] on functions returning Result or computed values
• #[inline] only on small functions in hot loops — never on public API
• Send + Sync bounds on trait objects crossing async boundaries
• #[derive(Debug)] on all public types; #[derive(Clone)] only when cheap
• feature flags for optional crate deps — #[cfg(feature = "...")]
• tests match the risk: unit, integration, property, snapshot, or domain-specific verification

Success criteria: The implementation fits the workspace’s systems-level quality bar.

Step 3: Verify the change

Use the narrowest relevant verification loop:

• cargo fmt
• cargo clippy -- -D warnings
• focused crate tests
• subsystem-specific tests such as proptest or snapshots when appropriate

Success criteria: The Rust surface is validated the way this workspace expects.

Guardrails

• Do not inline the whole Rust handbook in SKILL.md.
• Do not skip subsystem identification.
• Do not use anyhow in library crates unless the project specifically allows it there.
• Do not add disable-model-invocation; this is a normal domain skill.
• Do not leave unsafe invariants undocumented.

When To Load References

• references/stack.md Use for workspace/toolchain context.

• then only the task-relevant subsystem files under references/

Output Contract

Report:

1. which Rust references were loaded
2. the subsystem pattern applied
3. the change made
4. the verification run