dawiddutoit/custom-claude/architecture-validate-srp

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 - What this skill detects and validates
• Quick Start - Immediate SRP validation workflow
• When to Use This Skill - Triggers and integration points
• What This Skill Does - SRP definition and detection methods
• Instructions - Complete step-by-step validation process
• Usage Examples - Real-world validation scenarios
• Supporting Files - References and examples

Detailed Sections

• Validation Levels - Fast, thorough, and full analysis modes
• Detection Methods - 4-level validation approach
• Integration with Other Skills - code-review, validate-architecture, quality-gates
• Parameters - Configuration options
• Output Format - Text and JSON report formats
• Success Metrics - Accuracy and performance targets
• Requirements - Dependencies and installation
• Red Flags to Avoid - Common pitfalls
• Troubleshooting - Common issues and solutions
• 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 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

1. 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

1. 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

1. 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

Instructions

Step 1: Determine Validation Level

# 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:

./scripts/validate-srp.sh <path> --level=fast

Or manually with MCP tools:

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 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:

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

Or use God Class detection script:

./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:

# 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 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:

./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 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:

# 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 (should orchestrate only)
• Repositories containing orchestration (should be data access only)
• Optional config parameters (violates fail-fast)

See: references/srp-principles.md for actor identification guidance.

Step 7: Actor Analysis (Full Mode Only)

Guided questions for user:

1. "List all actors who would request changes to this class:"

• Example: "HR department, Accounting team, DBA"

1. "Can you group methods by actor?"

• Example: calculate_pay() → Accounting, report_hours() → HR

1. "How would you name classes split by actor?"

• Example: PayCalculator, HourReporter, EmployeeRepository

Actor count → Violation confidence:

• 1 actor: ✅ SRP compliant
• 2 actors: ⚠️ Warning (consider split)
• 3+ actors: ❌ Violation (must split)

Step 8: Generate Report

Report structure:

SRP Validation Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
✅ Passed: X/Y classes (Z%)
 
❌ Violations Found: N
 
[CRITICAL] God Class: ClassName (path/file.py:line)
  - Lines: X (threshold: 300)
  - Methods: Y (threshold: 15)
  - Constructor params: Z (threshold: 4)
  - ATFD: A, WMC: B, TCC: C
  - Actors detected: N (actor1, actor2, actor3)
  - Fix: Split into Class1 (actor1), Class2 (actor2), Class3 (actor3)
  - Estimated refactoring: A-B hours
 
[WARNING] Method Name Violation: method_and_other (path/file.py:line)
  - Method name contains 'and'
  - Confidence: 40%
  - Fix: Split into method() and other()
  - Estimated refactoring: 15-30 minutes
 
[WARNING] Long Method: process_request (path/file.py:line)
  - Lines: X (threshold: 50)
  - Cyclomatic complexity: Y (threshold: 10)
  - Confidence: 60%
  - Fix: Extract 2-3 smaller methods
  - Estimated refactoring: 30-60 minutes
 
Summary:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- X critical violations (must fix)
- Y warnings (should fix)
- Total estimated refactoring time: A-B hours
- Top priority: ClassName (god class)

Usage Examples

Example 1: Quick Pre-Commit Check

# User: "Quick SRP check before commit"
 
# Skill runs level: fast (5s)
→ Scans for method names with "and"
→ Reports 2 violations
 
Output:
⚠️ 2 SRP warnings found:
 
1. validate_and_save_user (src/services/user.py:45)
   - Method name contains 'and'
   - Fix: Split into validate_user() and save_user()
 
2. fetch_and_transform_data (src/utils/data.py:78)
   - Method name contains 'and'
   - Fix: Split into fetch_data() and transform_data()
 
Run with --thorough for complete analysis.

Example 2: Class Review (Default)

# User: "Review UserService for SRP compliance"
 
# Skill runs level: thorough (30s)
→ Naming patterns
→ Size metrics
→ Cohesion metrics
→ Constructor analysis
 
Output:
❌ UserService violates SRP (src/application/services/user_service.py:12)
 
Violations:
- Lines: 487 (threshold: 300) ❌
- Methods: 23 (threshold: 15) ⚠️
- Constructor params: 9 (threshold: 4) ❌
- ATFD: 12 (threshold: 5) ❌
- WMC: 89 (threshold: 47) ❌
- TCC: 0.21 (threshold: 0.33) ❌
 
Detected actors (3):
1. Authentication (login, logout, verify_token)
2. Profile Management (update_profile, get_profile, delete_account)
3. Notifications (send_welcome_email, send_reset_email)
 
Recommended split:
- UserAuthService: authentication methods
- UserProfileService: profile management
- UserNotificationService: notification methods
 
Estimated refactoring: 4-6 hours

Example 3: Deep Refactoring Analysis

# User: "Plan refactoring for PaymentProcessor - full SRP analysis"
 
# Skill runs level: full (5 min with user interaction)
→ All automated checks
→ Actor analysis questions
→ Refactoring plan
 
Questions asked:
1. "List actors who request changes to PaymentProcessor"
   User: "Finance team, Fraud detection, Customer support, Compliance"
 
2. "Group methods by actor"
   User provides grouping...
 
Output:
❌ PaymentProcessor is a God Class (4 actors detected)