design-philosophy

Design Philosophy Skill

Apply these principles when writing or reviewing code.

When to Use

• Proactively when designing new APIs, modules, or data structures
• When refactoring existing code
• When reviewing code for maintainability

Core Principles

1. Minimize Cognitive Load

Code should be easy to understand without loading too much into working memory.

Guidelines:

• Good Separation of Concerns (SoC) means fewer "things" to keep in mind
• Each module/function should have a single, clear responsibility
• Limit the number of concepts a reader must hold simultaneously

2. Progressive Disclosure

Reveal complexity only when needed.

Guidelines:

• Public APIs should be minimal and intuitive
• Advanced features should be discoverable but not in-your-face
• Documentation follows inverted pyramid: high-level first, details later
• Module structure should guide users from simple to advanced

3. Make Illegal States Unrepresentable

Use the type system to prevent bugs at compile time.

Guidelines:

• Prefer newtypes over primitives (e.g., Index instead of usize)
• Design enums and structs so invalid combinations cannot be constructed
• Move validation from runtime to compile time where possible
• See check-bounds-safety skill for exemplary patterns

4. Abstractions Must Earn Their Keep

An abstraction should reduce cognitive load, not add to it.

Guidelines:

• If understanding the abstraction requires more effort than the concrete code, don't abstract
• Good abstractions match mental models developers already have
• Three similar lines of code is often better than a premature abstraction
• Abstractions should hide complexity, not just move it

Supporting Files

• patterns.md - Detailed patterns with good/bad examples

Related Skills

• check-bounds-safety - Type-safe Index/Length patterns (exemplar of principle #3)
• organize-modules - Module organization for encapsulation (supports principle #1)
• write-documentation - Inverted pyramid documentation (supports principle #2)