| name | design-principles |
| description | Reference guide for design philosophy applied across all dev-strategy workflow skills. Use when you need to understand YAGNI, Last Responsible Moment, Kent Beck's 4 Simple Design Rules, Sufficient Design, and Just-In-Time Architecture principles. Provides context for planning, design, and implementation decisions. |
| skills-depend-on | [] |
Design Principles
Canonical reference for the design philosophy applied across all planning, implementation, and design contributions.
The 5 Core Principles
1. YAGNI — You Aren't Gonna Need It (Primary Principle)
Build only what is explicitly required for the current feature or phase.
- Don't add functionality, abstractions, or complexity for hypothetical future needs
- If it's not needed now, don't plan for it, design it, or implement it
- Prefer simple solutions that solve the immediate problem
- Applies equally to planning (don't plan hypothetical phases), design (don't design for future scenarios), and implementation (don't implement unused abstractions)
2. Last Responsible Moment (LRM)
Defer decisions until you have maximum information — not until it's too late, but not before you need to decide.
- Don't commit to complex solutions before understanding the full problem
- Wait for patterns to emerge naturally before abstracting
- In planning: only design what Phase N requires; defer Phase N+1 design to Phase N+1
- In implementation: only extract abstractions when you have 2–3 concrete use cases
3. Kent Beck's 4 Simple Design Rules
A design is sufficient when it (in order of priority):
- Passes tests — The code works as required
- Reveals intent — Code clearly expresses what it does
- No duplication — Don't repeat logic or structure
- Minimal elements — Use the fewest classes, methods, and abstractions possible
4. Sufficient Design / Implementation / Planning
The goal is actionable guidance that enables execution — not comprehensive documentation or perfect plans.
- Sufficient Planning: Provide enough detail for implementation without over-specifying
- Sufficient Implementation: Make it work correctly, not perfectly; avoid over-polishing
- Sufficient Design: Design enough to enable implementation; target < 100 lines for design docs
- Focus on "what to build" and "how it connects" rather than exhaustive "how"
5. Just-In-Time Architecture
Build what you need now. Refactor when complexity actually emerges.
Refactor when:
- You are literally copying and pasting code (actual duplication)
- The next phase requires a specific interface that does not exist
- The current structure actively prevents the next step
Never refactor for:
- Hypothetical future requirements
- "What if" scenarios
- Abstractions without 2–3 concrete use cases
Anti-Patterns Quick Reference
Critical Over-Engineering Red Flags
In Planning: Hypothetical phases, choosing complex strategies without evidence, over-specifying details
In Design: Design docs > 100 lines, designing for future constraints, designing for flexibility "just in case"
In Implementation: Creating interfaces/abstractions before 2-3 use cases, adding error handling for impossible scenarios, configuration systems before variations exist
Critical Under-Engineering Red Flags
In Design: No integration points, no success criteria, missing discovered constraints
In Implementation: No tests for required behavior, skipping pre-work validation (build/lint/tests), vague decision rationale
For the complete list with detailed examples and research anti-patterns, see anti-patterns.md.
How These Principles Apply
| Context | Primary Principle Applied |
|---|
| dev-strategy planning | YAGNI + LRM: plan current feature only |
| design-contribute sessions | Sufficient Design + YAGNI: design current phase only |
| dev-contribute implementation | YAGNI + Kent Beck: implement minimum to pass tests |
| Strategy selection | LRM: don't choose complex strategy without evidence |
| Between-phase refactoring | JIT Architecture: only refactor what next phase requires |
