agentsqripts/lib/srp-violations/USAGE-GUIDANCE.md

Comprehensive static code analysis toolkit for identifying technical debt, security vulnerabilities, performance issues, and code quality problems

# SRP Analyzer Usage Guidance

## Important: Scores Are Information, Not Mandates

The SRP analyzer provides violation scores to help you understand your codebase. **A HIGH score does not mean you must refactor.**

## Before You Refactor, Consider:

### 1. **Trade-offs of Splitting Files**
- ✅ Better adherence to strict SRP
- ❌ More files to navigate (we saw 70% increase)
- ❌ Separated related functions
- ❌ More import/export overhead

### 2. **When NOT to Split**
- Functions that work as a unit (open/close pairs)
- Small utility functions that share a theme
- Test files with multiple test cases
- Configuration files with setup functions

### 3. **When to Split**
- Genuinely unrelated functions in one file
- Files mixing multiple business domains
- Files over 200 lines with distinct sections
- When team agrees it improves clarity

## Interpreting Scores

- **Score 0-3**: Good enough - no action needed
- **Score 4-6**: Consider if functions belong together
- **Score 7-9**: Review, but only split if it makes sense
- **Score 10+**: Likely needs attention

## Remember

```
The tool shows: "File has 5 functions (HIGH violation)"
This means: "This file has 5 functions"
NOT: "You must split this file"
```

## Better Approach

1. Run the analyzer
2. Review HIGH scores
3. Ask: "Would splitting actually improve this code?"
4. Consider context and relationships
5. Make informed decisions, not mechanical ones

## Example Decision Process

```
File: validators.js
Functions: validateEmail(), validatePhone(), validateZipCode()
Score: 7 (HIGH)

Decision: Keep together
Why: These are related validation functions that make sense as a unit
```

## For AI Agents

Do not automatically refactor all violations. Ask:
- Is this refactoring improving the code?
- Will 300+ files be better than 200?
- Are these functions truly unrelated?

**The goal is maintainable code, not perfect scores.**