1 files changed, 13 insertions, 0 deletions
diff --git a/docs/rust-style-doctrine.md b/docs/rust-style-doctrine.md
new file mode 100644
index 0000000..1a1ef20
--- /dev/null
+++ b/docs/rust-style-doctrine.md
@@ -0,0 +1,13 @@
+# Rust Style Doctrine
+
+This doctrine deliberately rejects several pieces of conventional engineering wisdom. Do not silently translate it back into "clear, simple, approachable Rust." Where it conflicts with common advice, the conflict is usually intentional: agent-maintained code prefers static truth, compact representation, and powerful abstraction over novice readability, defensive ceremony, and lowest-common-denominator style. Notice the inversion and obey it.
+
+Rust code is a typed semantic artifact for agents, compilers, analyzers, and refactoring tools. Optimize for correctness, static structure, token economy, and intentional shape before ordinary human approachability. The code should look designed top-down around the domain, not accreted around incidents. Delete dead paths, compatibility husks, redundant layers, speculative knobs, ceremonial wrappers, and explanatory scaffolding. Hot sites should be small and exact; cold files may contain large definitions, tables, macros, derives, and helper machinery if they make the live surface leaner.
+
+Make illegal states unrepresentable. Stringly closed worlds, ad-hoc tuples, bool flags, walls of optionals, and folklore invariants are design failures. If a value has semantics, give it a domain type. Use enums, newtypes, structured IDs, typestates, phase-separated types, traits, generics, const generics, and total transformations to move truth into the type system. Prefer algebraic modeling, pattern matching, iterator algebra, composable APIs, and higher-order transforms. A good module should feel like a small calculus: constrained inputs, explicit states, predictable outputs.
+
+Overabstraction is not a crime. Weak abstraction is. The usual danger in agentic code is not that the model invents PLT machinery too powerful to follow; it is that it spills simple concrete structs, flags, guards, and named intermediates until the real invariant is smeared across the context window. Advanced math is often clearer to agents than bulk mundane plumbing. Trade shallow readability for structural correctness when the abstraction genuinely compresses the domain. DRY is stronger than YAGNI. Prefer one precise abstraction over five simple repetitions that must be kept mentally synchronized.
+
+Use the full language. Macros are first-class tools for uniformity, token economy, and invariant enforcement. Operator overloading is encouraged when the operation has the expected algebraic meaning. Prefer unqualified imports at call sites: import the symbol you mean, then use it bare. Prefer compact, domain-faithful names, including mathematical names, non-camel aliases, and Unicode identifiers when they match standard notation and reduce ambiguity. Destructure aggressively when it removes noise. Do not write Rust as Python with types sprinkled on top.
+
+Fail hard unless recovery is real. `Result` is for recoverable failure, not ritual anxiety; impossible states should be impossible, and irrecoverable states should panic early with domain context. Formatting, linting, type checking, dependency pruning, and semantic navigation are part of the build contract. Run `cargo fmt` after meaningful edits. Deny strict Clippy by default, including pedantic lints, with explicit recorded exceptions for low-value noise. Use rust-analyzer before textual search for definitions, references, diagnostics, and refactors. The machine should be austere, analyzable, and exact.