Design Patterns — Detect · Diagnose · Design · Deliver

The complete design patterns skill. From function-level GoF to system-level Microservices. Not just theory — it scans your code, finds the pain, and generates the fix.

Announce at start: "I'm using the design-patterns skill to analyze your codebase architecture and apply professional design patterns."

---

The Iron Laws

1. NO PATTERN WITHOUT PAIN
   — Don't apply Factory just because textbooks say so.
   — Show the EXACT line where current code breaks.

2. EVIDENCE BEFORE ELEGANCE
   — Measure complexity before proposing solutions.
   — If current code works, is testable, and is readable: LEAVE IT ALONE.

3. INCREMENTAL OVER REVOLUTIONARY
   — Never refactor 20 files in one PR.
   — One pattern, one module, one PR.

<HARD-GATE> Before proposing ANY pattern: 1. You MUST have scanned the target module's file tree 2. You MUST have identified at least ONE concrete anti-pattern with file:line evidence 3. You MUST have estimated the breaking impact (how many files change) If ANY of these is missing → STOP. Go back to scanning. </HARD-GATE>

---

When to Trigger

| Signal in Codebase | Severity | Pattern Category | |--------------------|----------|-----------------| | Function > 100 lines | 🟡 Medium | Code-Level (GoF) | | Class doing 5+ unrelated things | 🔴 High | SOLID violation | | Business logic inside API route/controller | 🔴 High | Architecture (Service Layer) | | Database queries scattered across files | 🟡 Medium | Architecture (Repository) | | Duplicated logic in 3+ places | 🟡 Medium | Code-Level (Strategy/Template) | | Circular imports between modules | 🔴 High | Architecture (Dependency Inversion) | | Monolith > 50k LOC with mixed concerns | 🔴 Critical | System (Microservices/DDD) | | No error recovery or retry logic | 🟡 Medium | System (Circuit Breaker) | | Hardcoded config values | 🟢 Low | Code-Level (Factory/Builder) |

---

The 4D Process: Detect → Diagnose → Design → Deliver

Phase 1: DETECT (Scan & Map)

digraph detect {
    rankdir=LR;
    scan [label="Scan\nFile Tree", shape=box, style=filled, fillcolor="#e6ffe6"];
    imports [label="Map\nImport Graph", shape=box];
    complexity [label="Score\nComplexity", shape=box];
    hotspots [label="Identify\nHotspots", shape=box, style=filled, fillcolor="#ffe6e6"];
    scan -> imports -> complexity -> hotspots;
}

What to scan:

1. File tree — list_dir recursively, understand module boundaries
2. Import graph — Who imports whom? Find coupling clusters
3. Function signatures — Count parameters (>5 = code smell)
4. File sizes — Lines per file (>300 = needs splitting)
5. Naming conventions — Are they consistent? (camelCase vs snake_case mix = chaos)

Output: A "Heat Map" of architectural debt:

🔴 HIGH DEBT:  src/api/routes.ts (450 lines, 12 functions, mixed DB + logic)
🟡 MED DEBT:   src/utils/helpers.ts (280 lines, "God module")
🟢 LOW DEBT:   src/models/user.ts (45 lines, clean data model)

Phase 2: DIAGNOSE (Identify Anti-Patterns)

For each hotspot, classify the anti-pattern:

| Anti-Pattern | Description | Evidence Required | |-------------|-------------|-------------------| | God Object | One class/module does everything | File > 300 LOC, > 8 methods | | Spaghetti Code | No clear flow, tangled logic | Cyclomatic complexity > 15 | | Logic Leakage | Business rules in wrong layer | DB queries in route handlers | | Shotgun Surgery | One change requires editing 5+ files | Grep shows same logic in multiple files | | Feature Envy | Module uses another module's data more than its own | Import analysis | | Primitive Obsession | Using strings/numbers instead of domain objects | No type definitions for core concepts | | Tight Coupling | Modules directly depend on implementation details | No interfaces/abstractions |

Output: Diagnosis table with file:line evidence.

Phase 3: DESIGN (Select Pattern)

Use the Pattern Selection Matrix to choose the right fix:

Scale 1: Code-Level (GoF + SOLID)

See: references/code-patterns.md

| Problem | Pattern | When to Use | |---------|---------|-------------| | Multiple object creation paths | Factory Method | 3+ constructors or conditional new | | Complex object construction | Builder | Object with 5+ optional params | | One global instance needed | Singleton | Config, DB connection pool | | Algorithm varies at runtime | Strategy | if/else chains selecting behavior | | React to state changes | Observer | Event systems, pub/sub | | Add behavior without modifying | Decorator | Middleware, logging, caching | | Simplify complex subsystem | Facade | External API wrapper | | Undo/redo operations | Command | Action history, job queues | | Process in steps | Template Method | ETL pipelines, test fixtures | | Tree-like structures | Composite | UI components, file systems |

Scale 2: Architecture-Level

See: references/architecture-patterns.md

| Problem | Pattern | When to Use | |---------|---------|-------------| | Logic mixed with infrastructure | Clean Architecture | New project or major refactor | | External dependencies hard to swap | Hexagonal (Ports & Adapters) | Multiple data sources | | Complex domain with many rules | DDD (Domain-Driven Design) | Enterprise, fintech, healthcare | | Business logic in controllers | Service Layer | Any app with > 10 endpoints | | DB access scattered | Repository Pattern | Any app with database | | Read/Write have different needs | CQRS | High-traffic, analytics-heavy |

Scale 3: System-Level

See: references/system-patterns.md

| Problem | Pattern | When to Use | |---------|---------|-------------| | Monolith too large to deploy | Microservices | Team > 5, independent deploy needed | | Services need loose coupling | Event-Driven Architecture | Async workflows, notifications | | Cascading failures | Circuit Breaker | External API calls | | Distributed transactions | Saga Pattern | Multi-service data consistency | | Traffic spikes | Bulkhead + Rate Limiter | Public APIs | | Config management across services | Sidecar / Ambassador | Kubernetes / containerized |

Phase 4: DELIVER (Generate Code)

This is what makes this skill different. After selecting the pattern, the skill generates production-ready boilerplate code specific to your framework.

Output includes:

1. New file structure — Where each file goes
2. Boilerplate code — Ready to paste, framework-specific
3. Migration steps — How to move old code into new structure
4. Test template — Test file for the new pattern
5. Rollback plan — How to undo if something breaks

---

Complexity Scoring Formula

Rate each module on 4 dimensions (1-5 each, max 20):

| Dimension | 1 (Clean) | 5 (Critical) | |-----------|-----------|---------------| | Size | < 100 LOC | > 500 LOC | | Coupling | 0-2 imports | > 10 imports | | Cohesion | Single responsibility | 5+ unrelated functions | | Testability | Unit testable | Requires full app to test |

Score interpretation:

• 4-8: ✅ Healthy — No action needed
• 9-13: 🟡 Moderate debt — Plan refactor in next sprint
• 14-17: 🔴 High debt — Refactor before adding features
• 18-20: 🚨 Critical — Stop feature work, refactor NOW

---

Red Flags — STOP and Rethink

• You're adding an interface for a class used in only 1 place → Over-engineering
• You're splitting a 50-line file into 3 files → Premature abstraction
• You're using DDD for a CRUD app → Wrong scale
• You're applying Microservices to a 2-person team → Organizational mismatch
• The refactored code is harder to read than the original → Failed refactor
• You can't explain the pattern in one sentence → You don't understand it

Common Rationalizations

| Excuse | Reality | |--------|---------| | "We need Clean Architecture for everything" | Clean Architecture for a TODO app is a war crime | | "Singleton is always bad" | DB connection pool is a legitimate Singleton | | "We should use microservices" | If you can't build a monolith, you can't build microservices | | "Interfaces everywhere for testability" | Mock the boundary, not every function | | "This pattern is industry standard" | Industry standard for YOUR scale? YOUR team? |

---

Output Format

Every design-patterns analysis MUST follow:

## 📊 Architecture Health Score: [X/20]

## 🔍 Detected Anti-Patterns
| # | Anti-Pattern | File:Line | Severity | Evidence |
|---|-------------|-----------|----------|----------|
| 1 | [name]      | [path:L]  | 🔴/🟡/🟢 | [description] |

## 💡 Recommended Patterns
| Anti-Pattern | → Pattern | Scale | Impact |
|-------------|-----------|-------|--------|
| [current]   | [proposed]| Code/Arch/System | [files affected] |

## 🏗️ Implementation Plan
### Step 1: [action]
- Files to create: [list]
- Files to modify: [list]
- Tests to add: [list]

## 📝 Generated Code
[Framework-specific boilerplate]

## ⚠️ Breaking Changes
[List of files/tests that will break]

## ↩️ Rollback Plan
[How to undo safely]

---

References

• references/code-patterns.md — 23 GoF patterns + 5 SOLID principles with production code examples
• references/architecture-patterns.md — Clean, Hexagonal, DDD, CQRS, Service Layer, Repository
• references/system-patterns.md — Microservices, Event-Driven, Circuit Breaker, Saga, Cloud patterns
• references/framework-catalog.md — Pattern implementations for Next.js, FastAPI, NestJS, Django, Express, Go
• references/testing-patterns.md — How to test every pattern (unit, integration, e2e) with real test code
• references/anti-patterns.md — 15 anti-patterns catalog with detection commands, severities, and cures
• references/migration-playbook.md — 5 step-by-step migration guides with verification checkpoints
• references/output-format.md — ADR template, Refactoring Report, Health Check, Pattern Comparison