name: architecture-validate-srp description: | Detect Single Responsibility Principle (SRP) violations using multi-dimensional analysis. Use when reviewing code for "SRP", "single responsibility", "god class", "doing too much", "too many dependencies", before commits, during refactoring, or as quality gate. Analyzes Python, JavaScript, TypeScript files with AST-based detection, metrics (TCC, ATFD, WMC), and project-specific patterns. Provides actionable fix guidance with refactoring estimates. allowed-tools:

• Read
• Grep
• Bash
• Glob
• mcp__ast-grep__dump_syntax_tree
• mcp__ast-grep__test_match_code_rule
• mcp__ast-grep__find_code
• mcp__ast-grep__find_code_by_rule
• mcp__project-watch-mcp__search_code

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

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

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"

2. "Can you group methods by actor?"

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

3. "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)

Actor breakdown:
1. Finance (3 methods): process_payment, refund_payment, calculate_fees
2. Fraud Detection (2 methods): check_fraud_score, block_suspicious
3. Customer Support (2 methods): get_transaction_history, dispute_charge
4. Compliance (2 methods): log_transaction, generate_audit_report

Refactoring plan:
Phase 1 (2 hours): Extract PaymentProcessor (Finance actor)
Phase 2 (1.5 hours): Extract FraudDetectionService
Phase 3 (1.5 hours): Extract TransactionHistoryService (Support)
Phase 4 (1 hour): Extract ComplianceReporter
Phase 5 (1 hour): Integration tests and validation

Total estimated time: 7 hours
Recommended approach: Incremental (1 phase per day)

Integration with Other Skills

With code-review

The code-review skill invokes SRP validation in Step 2 (Architectural Review) as a sub-check. When SRP violations are detected, they are reported as warnings in the overall code review report.

Integration point: Automatic invocation during code review workflow with level="fast" for speed.

With validate-architecture

The validate-architecture skill checks SRP compliance at the layer level, while this skill checks at the class/method level. Domain layers should have high cohesion (TCC > 0.5), and this skill can detect low cohesion violations.

Integration point: Cross-layer validation to ensure architectural boundaries maintain SRP.

With run-quality-gates

SRP validation can be added as an optional quality gate in .claude/quality-gates.json:

{
  "optional_gates": ["srp_validation"],
  "srp_threshold": "warning"
}

Set threshold to "critical" to block commits on violations.

With multi-file-refactor

When refactoring God Classes that span multiple files, use multi-file-refactor skill to coordinate changes. This skill identifies God Classes and provides refactoring guidance; multi-file-refactor executes the split.

Parameters

Usage:

# Default (thorough mode on src/)
Skill(command: "validate-srp")

# Custom path and level
Skill(command: "validate-srp --path=src/application --level=full")

# JSON output for tooling integration
Skill(command: "validate-srp --output_format=json")

Output Format

Text Output (Default)

See Step 8 in Instructions for complete example.

JSON Output

{
  "summary": {
    "total_classes": 45,
    "violations": 7,
    "warnings": 12,
    "passed": 26,
    "compliance_rate": 0.58
  },
  "violations": [
    {
      "severity": "critical",
      "type": "god_class",
      "class": "UserService",
      "file": "src/application/services/user_service.py",
      "line": 12,
      "metrics": {
        "lines": 487,
        "methods": 23,
        "constructor_params": 9,
        "atfd": 12,
        "wmc": 89,
        "tcc": 0.21
      },
      "actors": ["Authentication", "Profile", "Notifications"],
      "confidence": 0.80,
      "fix": "Split into UserAuthService, UserProfileService, UserNotificationService",
      "estimated_hours": 5.0
    }
  ],
  "warnings": [
    {
      "severity": "warning",
      "type": "method_naming",
      "method": "validate_and_save_user",
      "file": "src/services/user.py",
      "line": 45,
      "confidence": 0.40,
      "fix": "Split into validate_user() and save_user()",
      "estimated_minutes": 20
    }
  ]
}

Supporting Files

References

• references/srp-principles.md - Core SRP concepts, actor-driven definition, real-world examples, cohesion metrics formulas

Examples

• examples/examples.md - Overview of all examples with expected results
• examples/violation-naming-patterns.py - Methods with "and" in name, multiple actors
• examples/violation-god-class.py - Constructor with too many parameters
• examples/correct-single-actor.py - Proper SRP implementation with single actor

Scripts

• scripts/validate-srp.sh - Main validation script with 3 levels (fast/thorough/full)
• scripts/check-god-class.sh - God Class detection for individual files

Success Metrics

Utility Scripts

validate-srp.sh

Main validation script with multi-level analysis:

# Fast check (naming patterns only - 5 seconds)
./scripts/validate-srp.sh src/ --level=fast

# Thorough check (naming + size + constructors - 30 seconds)
./scripts/validate-srp.sh src/ --level=thorough

# Full analysis (with actor questions - 5 minutes)
./scripts/validate-srp.sh src/ --level=full

# JSON output for CI/CD integration
./scripts/validate-srp.sh src/ --output-format=json

check-god-class.sh

Focused God Class detection for single files:

# Check specific file
./scripts/check-god-class.sh src/services/user_service.py

# Returns:
# - Constructor parameter count
# - Method count
# - File size
# - God Class recommendation

Requirements

Minimum:

• Python 3.10+ (for AST analysis)
• Read, Grep, Bash, Glob tools
• Source code in supported language (Python/JS/TS)
• Validation scripts in scripts/ directory

Optional:

• radon for accurate metrics: uv pip install radon
• mcp__ast-grep__* tools for precise AST analysis
• mcp__project-watch-mcp__search_code for context

Installation:

# Make scripts executable
chmod +x scripts/*.sh

# Optional: Install radon for accurate metrics
uv pip install radon

# Verify installation
uv run radon --version

Red Flags to Avoid

Architectural Violations

1. God Classes - ATFD >5, WMC >47, TCC <0.33
2. Constructor Dependencies - >8 parameters
3. Method Naming - Methods with "and" in name
4. File Size - >500 lines per file

Detection Anti-Patterns

1. Ignoring warnings - Small violations compound into big issues
2. Not validating fixes - Re-run after refactoring
3. Skipping actor analysis - Metrics alone miss context
4. Assuming SRP = "one method" - SRP is actor-driven, not task-driven

Process Mistakes

1. Refactoring without tests - Always have test coverage first
2. Big bang refactoring - Incremental refactoring safer
3. Not estimating effort - Plan time for refactoring
4. Skipping after major changes - Validation most critical after refactoring

Troubleshooting

Issue: Too Many False Positives

Symptom: Small helper methods flagged as violations

Fix: Adjust thresholds in .claude/srp-config.json:

{
  "thresholds": {
    "class_lines": 400,
    "method_lines": 75,
    "constructor_params": 6
  }
}

Issue: Metrics Not Calculated

Symptom: "Metrics unavailable" in report

Fix: Install radon:

uv pip install radon

Or use simplified heuristics (less accurate but faster).

Issue: Can't Identify Actors

Symptom: Actor analysis unclear

Fix: Ask targeted questions:

1. "Who would request changes to this class?"
2. "Can you group methods by job role?"
3. "What teams interact with this code?"

Expected Benefits

See Also

• validate-architecture - Layer-level architecture validation
• code-review - Comprehensive pre-commit review (includes SRP)
• run-quality-gates - Quality gate orchestration
• multi-file-refactor - Coordinate SRP-driven refactoring
• @code-review-expert - Agent for code review guidance
• @architecture-guardian - Agent for architectural decisions
• ARCHITECTURE.md - Project architecture documentation

Last Updated: 2025-11-02 Version: 1.0.0