*Engineering excellence isn't about what you build—it's about how what you build enables others to build better things.*
<engineering_principles>
- **Strength Through Flexibility**: To influence a system, you must first understand its nature. Hard force creates resistance. Subtle guidance creates lasting change.
- **Software exists in three states**: The system as built, the system as observed, and the system as understood. Excellence requires alignment between all three.
- **Continuous verification**: Build positive signals into your systems—not just error detection, but continuous verification that things work as intended. The system should actively demonstrate its correctness, not just fail to demonstrate its incorrectness.
- **Test at extremes**: Production teaches you about normal operation; testing should reveal failure modes before they matter.
- **The Single Purpose Principle**: Build tools that solve exactly one problem completely rather than many problems partially. Quality compounds, but so do compromises.
- **Prefer Composition for Growth**: When you need new functionality, prefer building a new tool to extending an existing one. Growth should come from composition, not complication.
- **Plan for Death**: Set clear boundaries for when something is "complete enough" to begin its journey toward eventual obsolescence. All software dies; plan for it.
- **The Verifier**: Every production system should have a shadow that independently verifies its behavior. Split your architecture: one half does the work, one half confirms the work was done correctly. This isn't just about testing—it's about creating systems that can maintain themselves by continuously validating their own operation.
- **Exponentials giveth and exponentials taketh away**: Every conditional in your code represents exponential complexity. Every feature flag multiplies testing surface area. Every configuration option creates a new failure mode. Reduce choice through better design. Build systems with single paths from input to output when possible. When variation is necessary, make it explicit and verifiable.
</engineering_principles>
<three_fictions>
Every system should be built three times: once in mind, once in code, and once in monitoring. Allocate strategy across all three—pure vision accomplishes nothing, pure implementation creates chaos, and balance creates clarity.
Thus, every system exists in three forms:
1. The reality of its execution
2. The fiction it presents to observers
3. The fiction in our minds about how it works
Master engineers debug all three simultaneously. They know that the most subtle bugs live in the gaps between these representations.
When debugging, debug yourself first, then the system.
</three_fictions>
<compounding_effects>
Quality compounds. Craft compounds. Culture compounds.
Small, consistent choices in favor of excellence create systems that maintain themselves, teams that grow each other, and impact that scales beyond individual effort.
The goal isn't to be indispensable—it's to create systems so robust and teams so capable that your continued presence becomes optional, not required.
</compounding_effects>
<rust_idioms>
- Follow Rust naming conventions
- Use explicit typing where it improves readability
- Implement specialized constructor methods for enum variants when appropriate
- Provide builder-style methods with meaningful names (like `fn with_timeout(self, timeout: Duration)`) for configurable types
- Always place test modules at the bottom of the file
- Always organize module declarations with the following pattern:
- Group public modules first (pub mod bar;), sorted alphabetically
- Add a blank line
- Group private modules next (mod foo;)
- Add descriptive comments for each group
- Return Option<&T> rather than &Option<T> for accessor methods, using .as_ref()
- Re-export necessary types for doctest examples instead of marking them as ignore
- Prefix imports in doctests with # to hide them in documentation while still testing them
- Maintain semantic accuracy in error conversions (e.g., map HttpError to HttpError when possible)
- Avoid wrapping types that already use Arc internally (like ReqwestClient) in another Arc
- Remove unnecessary wrapper methods that don't add value beyond the methods they wrap
- Avoid adding comments explaining what was removed or not implemented - just remove the code
- Remove commented-out code and imports rather than leaving them in the codebase
- Avoid adding explanatory comments about why a function or operation isn't needed - simply implement the code correctly without calling attention to alternatives
- Prefer a single pattern for methods that do the same thing - avoid aliases that are similar
- Use appropriate error variants (e.g., HttpError for HTTP errors) rather than generic error types
- Create specific error types for common error cases instead of using a generic error with a message
- Don't use unwrap() or expect() in public APIs; instead, return Result to properly propagate errors
- tests/*.rs do not require a mod test block
- Prefer `#[allow(clippy::type_complexity)]` rather than using `type Foo = ComplexType` aliases
- Never run cargo check; prefer cargo clippy instead
</rust_idioms>