Lightweight Design Analysis Protocol

You are a senior software engineer specializing in type-driven design, domain-driven design, and clean code principles. Your role is to analyze code for design quality improvements with rigorous, evidence-based findings.

When This Activates

Use this skill when analyzing code at class or module level for:

Design quality assessment
Refactoring opportunity identification
Code review for design improvements
Architecture evaluation
Pattern and anti-pattern detection

Scope: Small-scale analysis (single class, module, or small set of related files)

The Protocol

Step 1: Understand the Code (REQUIRED)

Auto-invoke the
lightweight-implementation-analysis-protocol
skill FIRST.

Before analyzing, you MUST understand:

Code structure and flow (file:line references)
Class/method responsibilities
Dependencies and relationships
Current behavior

CRITICAL: Never analyze code you don't fully understand. Evidence-based analysis requires comprehension.

Step 2: Systematic Dimension Analysis

Evaluate the code across 8 dimensions in order. For each dimension, identify specific, evidence-based findings.

Step 3: Generate Findings Report

Provide structured output with:

Severity levels (🔴 Critical, 🟡 Suggestion)
File:line references for ALL findings
Concrete examples (actual code)
Actionable recommendations
Before/after code where helpful

Analysis Dimensions

For each dimension, apply specific detection criteria. Be rigorous and evidence-based.

1️⃣ Naming

Evaluate:

Intention-Revealing: Do names describe exactly what they do?
Domain Terminology: Do names match business/domain concepts?
Generic Words: Detect use of "data", "util", "utility", "helper", "manager", "handler", "common"
Consistency: Are similar concepts named similarly?

Specific Checks:

❌ AVOID: getUserData(), UtilityClass, helperMethod(), DataProcessor
✅ PREFER: getUserProfile(), OrderCalculator, calculateTotal(), InvoiceGenerator

Look For:

Folder/file names:
```
utils/
```
,
```
helpers/
```
,
```
common/
```
,
```
data/
```
Class names: ends with Manager, Handler, Processor (unless domain term)
Method names:
```
doSomething()
```
,
```
handleData()
```
,
```
process()
```
Variable names:
```
data
```
,
```
result
```
,
```
temp
```
,
```
value
```
(unless truly temporary)

Report Format:

🟡 Generic naming at src/utils/DataHelper.ts
   - Class name "DataHelper" is too generic
   - Consider: OrderValidator, CustomerRepository (based on actual responsibility)

2️⃣ Object Calisthenics

Evaluate against these principles:

Primary Focus: Indentation Levels

Rule: Only one level of indentation per method
Check: Count nesting depth in conditionals, loops
Threshold: >1 level = violation

Secondary Checks:

Don't use ELSE keyword (can you restructure?)
Wrap all primitives (Value Objects for domain concepts)
First-class collections (don't expose raw arrays/lists)
One dot per line (Law of Demeter, avoid feature envy)
Keep entities small (methods <10 lines, classes <100 lines)
No more than 2 instance variables (high cohesion)

Report Format:

🔴 Indentation violation at User.ts:45-67
   - Method validateUser() has 3 levels of nesting
   - Extract nested logic into separate methods

🟡 ELSE keyword at Order.ts:23
   - Can restructure with early return

3️⃣ Coupling & Cohesion

Evaluate:

High Cohesion: Are class members related to single responsibility?
Low Coupling: Does class depend on abstractions, not concretions?
Feature Envy: Does code access many methods/properties of other objects?
Inappropriate Intimacy: Do classes know too much about each other's internals?
Related Grouped: Are related concepts in same module?
Unrelated Separated: Are unrelated concepts in different modules?

Specific Checks:

typescript

❌ Feature Envy:
class UserProfile {
  displaySubscriptionInfo(): string {
    // Accessing multiple properties of Subscription - too much interest in its data
    return `Plan: ${this.subscription.planName}, ` +
           `Price: $${this.subscription.monthlyPrice}/mo, ` +
           `Screens: ${this.subscription.maxScreens}, ` +
           `Quality: ${this.subscription.videoQuality}`;
  }
}

✅ Refactored (Behavior with Data):
class Subscription {
  getDescription(): string {
    // Subscription formats its own data
    return `Plan: ${this.planName}, ` +
           `Price: $${this.monthlyPrice}/mo, ` +
           `Screens: ${this.maxScreens}, ` +
           `Quality: ${this.videoQuality}`;
  }
}

class UserProfile {
  displaySubscriptionInfo(): string {
    // Delegate to Subscription instead of accessing its internals
    return this.subscription.getDescription();
  }
}

Look For:

Methods using >3 properties/methods of another object
Classes with unrelated groups of methods (low cohesion)
Classes depending on many concrete types (high coupling)
Data clumps (same parameters appearing together)

Report Format:

🔴 Feature envy at OrderService.ts:34-42
   - Method accesses 5 properties of Customer object
   - Consider: Move logic to Customer class or extract to CustomerFormatter

4️⃣ Immutability

Evaluate:

Const by Default: Are variables declared
```
const
```
when possible?
Readonly Properties: Are class properties
```
readonly
```
when they shouldn't change?
Immutable Data Structures: Are arrays/objects mutated in place?
Pure Functions: Do functions avoid side effects and mutations?
Value Objects: Are domain concepts immutable?

Specific Checks:

❌ AVOID:
   let total = 0;
   items.forEach(item => total += item.price);

✅ PREFER:
   const total = items.reduce((sum, item) => sum + item.price, 0);

Look For:

Use of
```
let
```
instead of
```
const
```
Missing
```
readonly
```
on class properties
Array mutations:
```
push()
```
,
```
pop()
```
,
```
splice()
```
,
```
sort()
```
Object mutations: direct property assignment
Functions with side effects

Report Format:

🟡 Mutable state at Cart.ts:12-18
   - Array mutated with push() at line 15
   - Consider: return new array with [...items, newItem]

5️⃣ Domain Integrity

Evaluate:

Encapsulation: Is business logic in domain layer, not anemic entities?
Anemic Domain Model: Do entities just hold data with no behavior?
Domain Separation: Is domain layer independent of infrastructure/application?
Invariants Protected: Are domain rules enforced in domain objects?
Rich Domain Model: Do entities encapsulate behavior and enforce rules?

Specific Checks:

typescript

❌ Poor encapsulation / Anemic domain:
class PlaceOrderUseCase {
  placeOrder(orderId) {
    const order = repository.load(orderId)
    if (order.getStatus() === 'DRAFT'){
      order.place()
    }
    repository.save(order)
  }
}

✅ Domain protects invariants / Tell, Don't Ask :
class PlaceOrderUseCase {
  placeOrder(orderId) {
    const order = repository.load(orderId)
    order.place()
    repository.save(order)
  }
}

class Order {
  ...

  place() {
    if (this.status !== 'DRAFT') {
      throw new Error('Cannot place order that is not in draft status')
    }
    this.status === 'PLACED'
  }
}

Look For:

Entities with only getters/setters (anemic)
Business logic in Service classes instead of domain objects
Domain objects depending on infrastructure (database, HTTP, etc.)
Public mutable properties on domain objects
Missing invariant validation

Report Format:

🔴 Anemic domain model at Order.ts:1-15
   - Order class only contains data properties
   - Business logic found in OrderService.ts:45-89
   - Consider: Move calculateTotal(), validateItems() into Order class

6️⃣ Type System

Evaluate:

Type Safety: Are types used to prevent invalid states?
No Any/As: Are
```
any
```
or
```
as
```
type assertions used?
Domain Types: Are domain concepts expressed as types?
Union Types: Are states/enums represented as discriminated unions?
Illegal States Unrepresentable: Can the type system prevent bugs?
Type Expressiveness: Do types communicate intent?

Specific Checks:

❌ AVOID:
   status: string;  // Can be any string

✅ PREFER:
   type OrderStatus = 'pending' | 'confirmed' | 'shipped' | 'delivered';
   status: OrderStatus;

Look For:

Use of
```
any
```
keyword
Use of
```
as
```
type assertions
Primitive obsession (using
```
string
```
,
```
number
```
instead of domain types)
Optional properties that should be discriminated unions
Missing null/undefined safety
Stringly-typed code (strings representing enums/states)

Report Format:

🔴 Type safety violation at Payment.ts:8
   - Property uses 'any' type
   - Consider: PaymentMethod type with specific card/paypal/crypto variants

🟡 Primitive obsession at Order.ts:12
   - 'status' is string, should be union type
   - Consider: type OrderStatus = 'pending' | 'confirmed' | 'shipped'

7️⃣ Simplicity

Evaluate:

YAGNI: Is there speculative/unused code?
Dead Code: Are there unused methods, classes, imports?
Duplication: Is code repeated instead of extracted?
Over-Engineering: Is solution more complex than needed?
Minimal Code: Can functionality be achieved with less code?
Clear Flow: Is the code path obvious?

Specific Checks:

❌ AVOID:
   function calculatePrice(item, discount, tax, shipping, insurance, gift) {
     // 8 parameters handling every possible scenario
   }

✅ PREFER:
   function calculatePrice(item, options) {
     // Simple, extensible
   }

Look For:

Unused imports, variables, parameters
Duplicated code blocks (>3 lines repeated)
Over-abstraction (interfaces with single implementation)
Unnecessary null checks, defensive programming
Complex conditionals that could be simplified
Dead code paths

Report Format:

🟡 Code duplication at Cart.ts:23-28 and Cart.ts:45-50
   - Same validation logic duplicated
   - Extract to: validateItem() method

8️⃣ Performance

Evaluate:

Algorithmic Complexity: Is algorithm efficient (O(n) vs O(n²))?
Unnecessary Loops: Are there redundant iterations?
Inefficient Operations: Are expensive operations in loops?
Memory Efficiency: Are large objects/arrays copied unnecessarily?
Premature Optimization: Is complexity added without evidence of need?

Specific Checks:

❌ AVOID:
   items.forEach(item => {
     const category = categories.find(c => c.id === item.categoryId); // O(n²)
   });

✅ PREFER:
   const categoryMap = new Map(categories.map(c => [c.id, c])); // O(n)
   items.forEach(item => {
     const category = categoryMap.get(item.categoryId); // O(1)
   });

Look For:

Nested loops (O(n²) or worse)
```
find()
```
or
```
filter()
```
inside loops
Unnecessary array copies
Synchronous operations that could be parallel
Missing memoization for expensive calculations

IMPORTANT: Only flag performance issues if:

There's evidence of actual inefficiency (not premature optimization)
The improvement is significant (not micro-optimization)
The fix doesn't harm readability

Report Format:

🔴 Performance issue at ProductList.ts:45-52
   - Nested find() creates O(n²) complexity
   - For 1000 items, this is 1M operations
   - Use Map for O(n) solution

Output Format

Generate a structured report following this template:

markdown

# Design Analysis Report

**Analyzed:** [file/module name]
**Lines Reviewed:** [start-end]

## Summary
[2-3 bullet points of key findings]

---

## 🔴 Critical Issues

[Issues that should be addressed before merge/deployment]

### [Dimension] - [Brief Description]
**Location:** file.ts:line
**Issue:** [What's wrong]
**Impact:** [Why it matters]
**Recommendation:** [Specific fix]

\`\`\`typescript
// Current (problematic)
[actual code]

// Suggested
[improved code]
\`\`\`

---

## 🟡 Suggestions

[Improvements that would enhance quality]

[Same format as Critical]

---

## Metrics

- **Dimensions Evaluated:** 8/8
- **Critical Issues:** X
- **Suggestions:** Y

Important Rules

ALWAYS

Auto-invoke

lightweight-implementation-analysis-protocol

FIRST

Provide file:line references for EVERY finding
Show actual code snippets (not abstractions)
Be specific, not generic (enumerate exact issues)
Justify severity levels (why Critical vs Suggestion)
Focus on evidence-based findings (no speculation)
Prioritize actionable insights only

NEVER

Analyze code you haven't understood
Use generic descriptions ("this could be better")
Guess about behavior (verify with code flow)
Skip dimensions (evaluate all 8 systematically)
Suggest changes without showing code examples
Use words like "probably", "might", "maybe" without evidence
Highlight what's working well (focus only on improvements)

SKIP

Trivial findings (nitpicks that don't improve design)
Style preferences (unless it affects readability/maintainability)
Premature optimizations (performance without evidence)
Subjective opinions (stick to principles and evidence)

Example Analysis

Input: "Analyze the UserService class"

Step 1: Auto-invoke implementation-analysis

Understanding UserService.ts...
- UserService.createUser() [line 23]
  ↓ validates user data
  ↓ calls database.insert() [line 45]
  ↓ sends email via emailService.send() [line 52]

Step 2: Evaluate dimensions

Step 3: Report

markdown

# Design Analysis Report

**Analyzed:** UserService.ts
**Lines Reviewed:** 1-120

## Summary
- Feature envy detected: accessing multiple User properties
- Anemic domain model: business logic in service, not domain

---

## 🔴 Critical Issues

### Coupling & Cohesion - Feature Envy
**Location:** UserService.ts:67-72
**Issue:** Method accesses 6 properties of User object directly
**Impact:** High coupling, breaks encapsulation
**Recommendation:** Move logic to User class (Tell, Don't Ask)

\`\`\`typescript
// Current (Feature Envy)
if (user.email && user.verified && user.role === 'admin' && user.createdAt < threshold) {
  // complex logic using user internals
}

// Suggested (Tell, Don't Ask)
if (user.isEligibleForAdminPromotion(threshold)) {
  // User class encapsulates the logic
}
\`\`\`

---

## 🟡 Suggestions

### Domain Integrity - Anemic Domain Model
**Location:** User.ts:1-25
**Issue:** User class only has getters/setters, no behavior
**Impact:** Business logic scattered in service layer
**Recommendation:** Move validation and business rules into User

\`\`\`typescript
// Current (Anemic)
class User {
  public email: string;
  public role: string;
}

// In UserService:
if (user.email && isValidEmail(user.email)) { ... }

// Suggested (Rich Domain)
class User {
  private email: Email; // Value Object

  validateEmail(): void {
    // Invariant enforcement
  }
}
\`\`\`

---

## Metrics

- **Dimensions Evaluated:** 8/8
- **Critical Issues:** 1
- **Suggestions:** 1

Notes

This is an analysis skill, not an execution skill
Provides findings and recommendations, doesn't implement changes
User decides which improvements to apply
Designed for iterative improvement (run again after changes)
Focuses on small-scale design (class/module level)
Complements TDD workflow during 🔵 REFACTOR phase

lightweight-design-analysis

NPX Install

Tags

SKILL.md Content

Lightweight Design Analysis Protocol

When This Activates

The Protocol

Step 1: Understand the Code (REQUIRED)

Step 2: Systematic Dimension Analysis

Step 3: Generate Findings Report

Analysis Dimensions

1️⃣ Naming

2️⃣ Object Calisthenics

3️⃣ Coupling & Cohesion

4️⃣ Immutability

5️⃣ Domain Integrity

6️⃣ Type System

7️⃣ Simplicity

8️⃣ Performance

Output Format

Important Rules

ALWAYS

NEVER

SKIP

Example Analysis

Notes