# Lightweight Design Analysis

> A Claude Code skill for rigorous, evidence-based code design analysis across 8 quality dimensions

## What It Does

Analyzes code at the class or module level to identify design improvement opportunities across:

1. **Naming** - Intention-revealing names, domain terminology, avoiding generic words
2. **Object Calisthenics** - Especially indentation levels, small methods, single responsibility
3. **Coupling & Cohesion** - Feature envy, inappropriate intimacy, grouping related concepts
4. **Immutability** - Const by default, readonly properties, pure functions
5. **Domain Integrity** - Rich domain models, avoiding anemic entities, encapsulation
6. **Type System** - Making illegal states unrepresentable, avoiding `any`/`as`
7. **Simplicity** - Removing duplication, dead code, over-engineering
8. **Performance** - Algorithmic efficiency (only evidence-based, not premature optimization)

## When to Use

Invoke this skill when you want to:

- **Analyze code quality** before or after implementation
- **Find refactoring opportunities** in existing code
- **Review design** of a class or module
- **Identify anti-patterns** like anemic domain models or feature envy
- **Assess type safety** and domain modeling

**Perfect for:** The 🔵 REFACTOR phase of TDD workflow

## How It Works

1. **Understands First** - Auto-invokes `lightweight-implementation-analysis-protocol` to comprehend code flow
2. **Systematic Evaluation** - Analyzes all 8 dimensions with specific, evidence-based criteria
3. **Structured Report** - Provides findings with severity levels (🔴 Critical, 🟡 Suggestion)
4. **Actionable Recommendations** - Shows before/after code examples with file:line references

## Philosophy

This skill embodies principles from:

- **Type-Driven Development** (Scott Wlaschin) - Use types to express domain concepts
- **Domain-Driven Design** (Eric Evans) - Rich domain models with encapsulated behavior
- **Object Calisthenics** (Jeff Bay) - Strict coding constraints that enforce good design
- **Clean Code** (Robert C. Martin) - Intention-revealing names, single responsibility
- **Working Effectively with Legacy Code** (Michael Feathers) - Identifying improvement opportunities

## Example Usage

```
User: "Analyze the Order class for design improvements"

Claude: [Auto-invokes implementation-analysis to understand Order.ts]

Claude: [Generates design analysis report]

# Design Analysis Report

**Analyzed:** Order.ts
**Lines Reviewed:** 1-85

## Summary
- Anemic domain model detected: Order has no business logic
- Feature envy: OrderService accesses many Order properties

## 🔴 Critical Issues

### Domain Integrity - Anemic Domain Model
**Location:** Order.ts:1-30
**Issue:** Order class only stores data, no business behavior
**Impact:** Business logic scattered across services, hard to maintain
**Recommendation:** Move calculateTotal() and validateItems() into Order

[Code examples...]

## 🟡 Suggestions

### Object Calisthenics - Indentation
**Location:** Order.ts:42-58
**Issue:** Method has 3 levels of nesting
**Recommendation:** Extract nested logic to separate methods

[Code examples...]

## Metrics
- Dimensions Evaluated: 8/8
- Critical Issues: 1
- Suggestions: 2
```

## Output Format

Every finding includes:

- **Severity Level:** 🔴 Critical | 🟡 Suggestion
- **Dimension:** Which of the 8 dimensions
- **Location:** Exact file:line reference
- **Issue:** What's wrong (evidence-based)
- **Impact:** Why it matters
- **Recommendation:** Specific, actionable fix
- **Code Example:** Before/after snippets

## Integration

- **Auto-invokes** `lightweight-implementation-analysis-protocol` to understand code first
- **Complements** your TDD workflow during refactoring phases
- **Iterative** - Run again after applying improvements to measure progress

## Key Principles

✅ **Evidence-Based** - Every finding has file:line reference and code example
✅ **Specific, Not Generic** - Explicit detection criteria (2.54x more effective)
✅ **Systematic** - Evaluates all 8 dimensions, nothing missed
✅ **Actionable** - Shows exact code improvements, not abstract suggestions
✅ **Rigorous** - No speculation ("probably", "maybe"), only verified findings
✅ **Focused** - Only highlights issues and improvements, no noise

❌ **Never Guesses** - Understands code flow first via implementation-analysis
❌ **Not Execution** - Provides analysis and recommendations, doesn't implement
❌ **Not Nitpicky** - Skips trivial style preferences, focuses on design
❌ **Not Premature** - Only flags performance issues with evidence of inefficiency

## Version History

- **v1.0.0** - Initial release with 8 core dimensions

## Contributing

This is a living skill that evolves based on what works. After using it, consider:

- Adding new dimensions if gaps are discovered
- Refining criteria if false positives occur
- Updating examples with real-world findings
- Adjusting severity thresholds based on experience

## Author

Created for iterative, evidence-based code design improvement.