markitect-main/examples/design-patterns/DontRepeatYourself.md

# Design Principle: Don’t Repeat Yourself (DRY)

## Meta
- **Name:** Don’t Repeat Yourself
- **ShortName:** DRY
- **Version:** 0.1
- **Status:** Stable
- **Tags:** maintainability, refactoring, architecture, quality
- **RelatedPrinciples:** Single Responsibility, YAGNI, Separation of Concerns

---

## Intent
Reduce maintenance cost and behavioral drift by ensuring that each piece of
knowledge, rule, or decision logic has a single authoritative representation
in the codebase.

---

## CoreStatement
A codebase violates DRY when the same knowledge is expressed in multiple places
such that a change would require edits in more than one location or risks
inconsistent behavior.

---

## Scope

### InScope
- Business rules and decision logic
- Algorithms and validation logic
- Data schemas, DTOs, and field definitions
- Configuration values and feature flags
- Repeated workflows or orchestration logic
- Test setup and invariant test scenarios

### OutOfScope
- Superficial textual similarity without shared meaning
- Intentional duplication for isolation or clarity
- Early-stage exploratory code where abstractions are not yet clear
- Performance-driven duplication with explicit justification

---

## InterpretationGuidelines

### What “Repeat” Means
DRY is about **duplication of knowledge**, not duplication of text.

Examples of knowledge duplication:
- The same validation rule implemented in multiple services
- Identical conditional logic controlling the same behavior
- The same data structure defined independently in multiple modules

### Common Misinterpretations
- “Any repeated code is bad” (false)
- “DRY means maximum abstraction” (false)
- “Utility modules automatically improve DRY” (often false)

---

## DetectionHeuristics

### Structural Signals
- Functions with highly similar bodies and signatures
- Repeated constants, strings, regexes, or SQL fragments
- Parallel modules with mirrored internal structure

### Semantic Signals
- Identical error messages or validation rules in different layers
- Repeated mapping logic between the same concepts
- Copy-paste variations differing only in naming

### Change-Cost Signals
- A requirement change touches multiple files for the same reason
- Fixes applied in one location but missing in others
- Tests failing inconsistently after partial updates

---

## DiagnosticQuestions
1. Is this duplication representing the same rule or policy?
2. If this rule changes, how many places must be updated?
3. Is the duplicated logic stable or likely to evolve?
4. Are the differences intentional or accidental?
5. Where is the natural “source of truth” for this knowledge?
6. Would abstraction reduce or increase cognitive load?

---

## RecommendedActions

### Low-Risk Refactors
- Extract constants or configuration values
- Centralize literals and error messages
- Introduce shared test fixtures or helpers

### Medium-Risk Refactors
- Extract pure helper functions
- Introduce shared domain services or modules
- Unify schema/type definitions

### High-Risk Refactors
- Introduce strategy/template patterns
- Merge parallel subsystems
- Redesign domain boundaries to align ownership of rules

---

## AcceptanceCriteria
- Each rule or behavior has a single authoritative implementation
- Required changes affect fewer locations than before
- Naming reflects domain meaning, not technical convenience
- Tests pass without behavior regression
- Coupling does not increase unintentionally

---

## AntiPatterns
- “God” utility modules with unrelated helpers
- Over-generalized abstractions with many parameters
- Shared code across domains that should evolve independently
- Premature abstraction of coincidental similarities
- Hiding meaningful differences behind generic interfaces

---

## Tradeoffs
Applying DRY may:
- Increase indirection
- Reduce local readability
- Introduce coupling between modules

These costs are acceptable only when outweighed by reduced change cost
and increased behavioral consistency.

---

## AgentUsage

### When to Apply This Lens
- During refactoring or maintenance work
- When change requests repeatedly touch similar code
- When bugs recur due to partial updates
- During architectural consolidation

### When to Suspend This Lens
- During early exploration or prototyping
- When future variability is unclear
- When isolation is more valuable than reuse

### Expected Agent Output
- Identified DRY violations with locations
- Rationale for why duplication matters
- Volatility assessment (stable vs evolving)
- Recommended refactor type and target
- Risk notes and minimal patch sequence

xxx