architecture-validate-srp

What this skill does

# Validate Single Responsibility Principle (SRP)

**Automated detection of SRP violations using actor-driven analysis, metrics, and AST patterns.**

## Purpose

Detect Single Responsibility Principle violations using multi-dimensional analysis including naming patterns, class metrics, method complexity, cohesion measurements, and project-specific architectural patterns. Provides actionable fix guidance with confidence scoring and refactoring estimates.

## Table of Contents

### Core Sections
- [Purpose](#purpose) - What this skill detects and validates
- [Quick Start](#quick-start) - Immediate SRP validation workflow
- [When to Use This Skill](#when-to-use-this-skill) - Triggers and integration points
- [What This Skill Does](#what-this-skill-does) - SRP definition and detection methods
- [Instructions](#instructions) - Complete step-by-step validation process
- [Usage Examples](#usage-examples) - Real-world validation scenarios
- [Supporting Files](#supporting-files) - References and examples

### Detailed Sections
- [Validation Levels](#validation-levels) - Fast, thorough, and full analysis modes
- [Detection Methods](#detection-methods-multi-dimensional) - 4-level validation approach
- [Integration with Other Skills](#integration-with-other-skills) - code-review, validate-architecture, quality-gates
- [Parameters](#parameters) - Configuration options
- [Output Format](#output-format) - Text and JSON report formats
- [Success Metrics](#success-metrics) - Accuracy and performance targets
- [Requirements](#requirements) - Dependencies and installation
- [Red Flags to Avoid](#red-flags-to-avoid) - Common pitfalls
- [Troubleshooting](#troubleshooting) - Common issues and solutions
- [Expected Benefits](#expected-benefits) - Metrics and improvements

## Quick Start

**User asks:** "Check if this class is doing too much" or "Validate SRP compliance"

**What happens:**
1. Scans code for SRP violations (naming, size, complexity, dependencies)
2. Calculates cohesion metrics (TCC, ATFD, WMC)
3. Detects project-specific anti-patterns
4. Reports violations with specific refactoring guidance
5. Estimates refactoring time and effort

**Result:** ✅ SRP compliant OR ❌ Violations with actionable fixes

## When to Use This Skill

**Invoke this skill when:**
- User asks: "check SRP", "single responsibility", "is this doing too much"
- User asks: "god class", "too many dependencies", "method too long"
- Before commit (as part of `code-review` skill)
- During refactoring or architectural review
- As quality gate (via `run-quality-gates` skill)
- When class/method feels complex but can't articulate why

**Integration triggers:**
- `code-review` skill Step 2: Architectural Review (SRP sub-check)
- `validate-architecture` skill: SRP at layer level
- `run-quality-gates` skill: Optional SRP quality gate
- `multi-file-refactor` skill: SRP-driven refactoring coordination

## What This Skill Does

### SRP Definition (Actor-Driven)

**Robert C. Martin:** "A module should be responsible to one, and only one, actor."

- **Actor**: A group of users or stakeholders who would request changes
- **NOT** "do one thing" (task-driven) - a class can have multiple methods
- **IS** "have one reason to change" (actor-driven)

**Example:** See [examples/violation-naming-patterns.py](./examples/violation-naming-patterns.py) for violation and correct implementation showing Employee class serving 3 actors (Accounting, HR, DBA) and the correct split into PayCalculator, HourReporter, and EmployeeRepository.

### Detection Methods (Multi-Dimensional)

This skill uses **4 validation levels**:

1. **Level 1 (Fast, 5s)**: Naming patterns via AST-grep
   - Methods with "and" in name → 40% confidence violation
   - Quick scan of entire codebase

2. **Level 2 (Fast, 10s)**: Size metrics via AST analysis
   - Class >300 lines → Review needed
   - Method >50 lines → 60% confidence violation
   - >15 methods per class → Review needed

3. **Level 3 (Moderate, 30s)**: Cohesion metrics
   - God Class: ATFD >5 AND WMC >47 AND TCC <0.33 → 80% confidence
   - Constructor >4 params (warning), >8 params (critical) → 75% confidence

4. **Level 4 (Manual, 5min)**: Actor analysis (guided questions)
   - "How many actors would request changes to this class?"
   - "Can you split by actor responsibility?"

**Default mode:** Level 2 (Fast + Size metrics) - balance speed and accuracy

### Validation Levels

| Level | Speed | Checks | Use When |
|-------|-------|--------|----------|
| `fast` | 5s | Naming patterns only | Quick pre-commit scan |
| `thorough` | 30s | Naming + Size + Metrics | Normal workflow (default) |
| `full` | 5min | All checks + Actor analysis | Deep refactoring review |

## Instructions

### Step 1: Determine Validation Level

```bash
# User request → Validation level
"quick check" → fast
"review this class" → thorough (default)
"plan refactoring" → full
```

### Step 2: Detect Naming Violations (All Levels)

**Pattern 1: Methods with "and" in name (40% confidence)**

Use the validation script to detect naming violations:

**Using validation script:**
```bash
./scripts/validate-srp.sh <path> --level=fast
```

**Or manually with MCP tools:**
```bash
mcp__ast-grep__find_code(
    pattern="def $NAME_and_$REST",
    project_folder="/path/to/project",
    language="python"
)
```

**Example violations and fixes:** See [examples/violation-naming-patterns.py](./examples/violation-naming-patterns.py) showing validate_and_save_user() violation and the correct split into validate_user() and save_user().

### Step 3: Analyze Size Metrics (Thorough+)

**Pattern 2: Class size (300+ lines → review)**

Use the validation script for size analysis:

```bash
./scripts/validate-srp.sh <path> --level=thorough
```

**Or use God Class detection script:**

```bash
./scripts/check-god-class.sh <file.py>
```

**Thresholds:**
- Class: >300 lines = warning, >500 lines = critical
- Method: >50 lines = warning, >100 lines = critical
- Methods per class: >15 = warning, >25 = critical

### Step 4: Calculate Cohesion Metrics (Thorough+)

**God Class Detection (80% confidence):**
- **ATFD** (Access to Foreign Data): >5 = excessive coupling
- **WMC** (Weighted Methods per Class): >47 = too complex
- **TCC** (Tight Class Cohesion): <0.33 = low cohesion

**Formula:** `ATFD >5 AND WMC >47 AND TCC <0.33 → God Class`

**Calculate metrics using radon:**

```bash
# If radon available
uv run radon cc src/ -a -nb  # Cyclomatic complexity (WMC proxy)
uv run radon raw src/        # Raw metrics
```

**See:** [references/srp-principles.md](./references/srp-principles.md) for detailed metric calculations and formulas.

### Step 5: Detect Constructor Dependencies (Thorough+)

**Pattern 4: Constructor parameters (>4 warning, >8 critical)**

Use the God Class detection script:

```bash
./scripts/check-god-class.sh <file.py>
```

**Thresholds (75% confidence):**
- 1-4 params: ✅ Good
- 5-8 params: ⚠️ Warning (consider parameter object)
- 9+ params: ❌ Critical (God Class indicator)

**Example violations and fixes:** See [examples/violation-god-class.py](./examples/violation-god-class.py) showing UserService with 9 constructor parameters and the correct split into UserAuthService, UserNotificationService, and UserAnalytics.

### Step 6: Detect Project-Specific Patterns

**Read CLAUDE.md for project anti-patterns:**

Check for project-specific SRP violations using grep:

```bash
# Pattern 1: Optional config parameters (project anti-pattern)
grep -rn "config.*Optional\|config.*None.*=" src/

# Pattern 2: Domain entities doing I/O (layer violation)
grep -r "import.*requests\|import.*database" domain/

# Pattern 3: Application services with business logic
grep -r "def calculate\|def compute" application/services/

# Pattern 4: Repositories with orchestration
grep -A 10 "class.*Repository" infrastructure/repositories/
```

**Common project-specific violations:**
- Domain entities importing infrastructure
- Application services implementing business logic (sho