Architecture Single Responsibility Principle

Single Responsibility Principle Validation

Table of Contents

Quick Start → When to Use | Triggers | What It Does | Examples

How to Implement → Detection Process | Validation Levels | Expected Output

Patterns & Scripts → Detection Patterns | Detection Script | Project Patterns

Help → Troubleshooting | Requirements | Integration

Reference → SRP Principles | Detection Patterns | Quick Reference

When to Use This Skill

MANDATORY in these situations:

• Before declaring architectural refactoring complete
• During code reviews for SRP compliance
• Before commits that modify class structure
• When user says "check SRP", "validate single responsibility"
• After implementing new services or handlers

Triggers

Trigger with phrases like:

• "check SRP"
• "single responsibility"
• "is this doing too much?"
• "validate SRP"
• "god class check"
• "class too large"
• "method doing too much"

Purpose

Automatically detect Single Responsibility Principle violations using multi-dimensional analysis: naming patterns, class metrics, method complexity, and project-specific architectural patterns. Provides actionable fix guidance with confidence scoring.

Quick Start

See usage-examples.md for complete examples with expected output.

Basic usage:

• Validate entire codebase: Skill(command: "single-responsibility-principle")
• Fast pre-commit check: Skill(command: "single-responsibility-principle --level=fast")
• Validate specific path: Skill(command: "single-responsibility-principle --path=src/services/")
• JSON output for CI/CD: Skill(command: "single-responsibility-principle --format=json")

Instructions

Step 1: Determine Validation Level

Choose based on context:

• fast: Naming patterns + basic size metrics (5-10s, pre-commit)
• thorough: + Complexity metrics + project patterns (30s, default)
• full: + Actor analysis + cohesion metrics (1-2min, comprehensive)

Step 2: Run Detection

Execute multi-dimensional detection:

1. Naming Analysis (ast-grep):

   • Methods with "and" in name → 40% confidence violation
   • Files named "manager", "handler", "utils" → review needed

2. Size Metrics (AST or line count):

   • Classes >300 lines → review needed
   • Files >500 lines → review needed
   • Methods >50 lines → 60% confidence violation
   • Classes >15 methods → review needed

3. Dependency Analysis (constructor params):

   • 5-8 params → warning (75% confidence)

   • 8 params → critical (90% confidence)

4. Complexity Metrics (radon if available):

   • Cyclomatic complexity >10 → 60% confidence violation
   • God class detection (ATFD >5 AND WMC >47 AND TCC <0.33) → 80% confidence

5. Project-Specific Patterns:

   • Optional config parameters → critical violation
   • Domain entities doing I/O → critical violation
   • Application services with business logic → violation
   • Repositories with orchestration → violation

Step 3: Categorize Violations

Assign confidence levels:

• CRITICAL (80%+): God classes, optional config, architecture violations
• WARNING (60-80%): Long methods, many dependencies, complexity
• REVIEW (40-60%): Naming patterns, size thresholds

Step 4: Generate Fix Guidance

For each violation:

1. Identify specific issue (line, pattern, metric)
2. Suggest split strategy (actor-based)
3. Provide example (from references/project-patterns.md)
4. Estimate refactoring time

Step 5: Output Report

Format results:

Single Responsibility Principle Validation Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Scope: path/to/code
Level: thorough
Files Analyzed: X
Classes Analyzed: Y

✅ Passed: Z/Y classes (P%)

❌ Violations Found: N

[CRITICAL] God Class: ClassName (path/file.py:45)
  - Lines: 450 (threshold: 300)
  - Methods: 23 (threshold: 15)
  - Constructor params: 9 (threshold: 4)
  - Complexity metrics: ATFD=8, WMC=52, TCC=0.28
  - Actors identified: 3 (persistence, validation, coordination)
  - Fix: Split into:
    * ClassNamePersistence (handles database operations)
    * ClassNameValidator (handles validation logic)
    * ClassNameCoordinator (orchestrates workflow)
  - Estimated effort: 4-6 hours

[WARNING] Method Name Violation: validate_and_save_user (path/file.py:120)
  - Method name contains 'and' (40% confidence)
  - Fix: Split into:
    * validate_user() -> ServiceResult[User]
    * save_user(user: User) -> ServiceResult[None]
  - Estimated effort: 30 minutes

[WARNING] Long Method: process_data (path/file.py:200)
  - Lines: 75 (threshold: 50)
  - Cyclomatic complexity: 14 (threshold: 10)
  - Fix: Extract helper methods for each logical section
  - Estimated effort: 1-2 hours

Summary:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Critical: X violations
Warnings: Y violations
Reviews needed: Z items

Total estimated refactoring time: A-B hours

Next Steps:
1. Address critical violations first (God classes, architecture)
2. Refactor method name violations
3. Break down long methods
4. Review class sizes for potential splits

Examples

See usage-examples.md for complete usage examples including:

• Example 1: Validate entire codebase
• Example 2: Fast pre-commit check
• Example 3: Validate specific service
• Example 4: JSON output for CI/CD

All examples include expected output and timing information.

Requirements

Required Tools

• mcp__ast-grep__find_code: AST-based pattern detection
• Read: File analysis
• Bash: Metrics calculation (radon if available)
• Grep: Quick pattern matching
• Glob: File discovery

Optional Dependencies

• radon: Python complexity metrics (pip install radon)
  • If unavailable: Use basic AST metrics (line counts, method counts)
• pylint: Additional metrics (pip install pylint)
  • If unavailable: Skip cohesion metrics (TCC, ATFD)

Installation

# Install optional metrics tools
uv pip install radon pylint

# Verify installation
radon --version
pylint --version

Detection Patterns

The skill uses multi-dimensional detection patterns. See detection-patterns.md for complete AST patterns and metrics thresholds.

Quick detection using provided script:

# Run all detection patterns
./scripts/detect-patterns.sh all /path/to/project

# Run specific pattern
./scripts/detect-patterns.sh method-and /path/to/project
./scripts/detect-patterns.sh god-class /path/to/project
./scripts/detect-patterns.sh constructor-params /path/to/project
./scripts/detect-patterns.sh optional-config /path/to/project

See detect-patterns.sh for implementation details.

Integration Points

With code-review Skill

Add SRP validation as Step 2 sub-check:

## Step 2: Single Responsibility Review
- [ ] Run `single-responsibility-principle --level=fast`
- [ ] Address critical violations
- [ ] Document acceptable warnings

With validate-architecture Skill

Include SRP at layer level:

# Check domain entities don't do I/O
# Check application services don't contain business logic
# Check repositories only do data access

With run-quality-gates Skill

Add as quality gate:

# In check_all.sh or quality gate hook
Skill(command: "single-responsibility-principle --level=fast")
# Block commit if critical violations found

With multi-file-refactor Skill

Coordinate SRP refactoring across files:

# Identify all God classes
# Plan extraction strategy
# Use MultiEdit for atomic refactoring

Troubleshooting

"radon not found"

Solution: Install with uv pip install radon or skip complexity metrics (use --level=fast)

"Too many false positives"

Solution: Adjust thresholds in detection patterns or focus on critical violations only

"Analysis too slow"

Solution: Use --level=fast or --path=specific/directory to narrow scope

"Missing violations"

Solution: Use --level=full for comprehensive analysis including actor identification

See Also

• srp-principles.md - Core SRP concepts and misconceptions
• detection-patterns.md - AST patterns and metrics thresholds
• project-patterns.md - project-watch-mcp specific patterns
• quick-reference.md - One-page SRP checklist