Initial commit

skills/lightweight-design-analysis/README.md

@@ -0,0 +1,137 @@
+# 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.