ln-624-code-quality-auditor
Code quality audit worker (L3). Checks cyclomatic complexity, deep nesting, long methods, god classes, O(n²) algorithms, N+1 queries, magic numbers, decentralized constants, duplicate constants. Returns findings with severity, location, effort, recommendations.
When & Why to Use This Skill
The Code Quality Auditor is an advanced L3 worker designed to automate deep technical audits of codebases for enhanced maintainability and performance. It systematically identifies critical issues such as high cyclomatic complexity, deep nesting, inefficient O(n²) algorithms, and N+1 database queries. By delivering structured findings with severity levels, precise locations, and actionable recommendations, it empowers development teams to proactively manage technical debt and ensure code compliance with industry best practices.
Use Cases
- Automated Pull Request Audits: Integrate into development workflows to automatically flag complex logic, deep nesting, or 'God Classes' before code merges.
- Performance Bottleneck Detection: Identify inefficient algorithmic patterns like O(n²) loops and N+1 ORM queries in API handlers to prevent production scaling issues.
- Technical Debt Assessment: Scan legacy codebases to locate magic numbers, decentralized constants, and oversized modules to prioritize refactoring efforts.
- Domain-Aware Quality Scanning: Perform targeted audits on specific business domains or microservices to ensure localized code quality without scanning the entire repository.
| name | ln-624-code-quality-auditor |
|---|---|
| description | Code quality audit worker (L3). Checks cyclomatic complexity, deep nesting, long methods, god classes, O(n²) algorithms, N+1 queries, magic numbers, decentralized constants, duplicate constants. Returns findings with severity, location, effort, recommendations. |
| allowed-tools | Read, Grep, Glob, Bash |
Code Quality Auditor (L3 Worker)
Specialized worker auditing code complexity, algorithms, and constants management.
Purpose & Scope
- Worker in ln-620 coordinator pipeline - invoked by ln-620-codebase-auditor
- Audit code quality (Categories 5+6+NEW: Medium Priority)
- Check complexity metrics, algorithmic efficiency, constants management
- Return structured findings with severity, location, effort, recommendations
- Calculate compliance score (X/10) for Code Quality category
Inputs (from Coordinator)
Receives contextStore with:
tech_stack- detected tech stack (languages, frameworks)best_practices- researched best practices from MCPprinciples- project-specific principles from docs/principles.mdcodebase_root- root path of codebase
Domain-aware fields (NEW):
domain_mode:"domain-aware"|"global"(optional, defaults to "global")current_domain:{name, path}when domain_mode="domain-aware"
Example contextStore (domain-aware):
{
"tech_stack": {...},
"best_practices": {...},
"principles": {...},
"codebase_root": "/project",
"domain_mode": "domain-aware",
"current_domain": {
"name": "orders",
"path": "src/orders"
}
}
Workflow
Parse context from contextStore
- Extract tech_stack, best_practices, principles
- Determine scan_path (NEW):
IF domain_mode == "domain-aware": scan_path = codebase_root + "/" + current_domain.path domain_name = current_domain.name ELSE: scan_path = codebase_root domain_name = null
Scan codebase for violations
- All Grep/Glob patterns use
scan_path(not codebase_root) - Example:
Grep(pattern="if.*if.*if", path=scan_path)for nesting detection
- All Grep/Glob patterns use
Collect findings with severity, location, effort, recommendation
- Tag each finding with
domain: domain_name(if domain-aware)
- Tag each finding with
Calculate score using penalty algorithm
Return JSON result to coordinator
- Include
domainandscan_pathfields (if domain-aware)
- Include
Audit Rules (Priority: MEDIUM)
1. Cyclomatic Complexity
What: Too many decision points in single function (> 10)
Detection:
- Count if/else, switch/case, ternary, &&, ||, for, while
- Use tools:
eslint-plugin-complexity,radon(Python),gocyclo(Go)
Severity:
- HIGH: Complexity > 20 (extremely hard to test)
- MEDIUM: Complexity 11-20 (refactor recommended)
- LOW: Complexity 8-10 (acceptable but monitor)
Recommendation: Split function, extract helper methods, use early returns
Effort: M-L (depends on complexity)
2. Deep Nesting (> 4 levels)
What: Nested if/for/while blocks too deep
Detection:
- Count indentation levels
- Pattern: if { if { if { if { if { ... } } } } }
Severity:
- HIGH: > 6 levels (unreadable)
- MEDIUM: 5-6 levels
- LOW: 4 levels
Recommendation: Extract functions, use guard clauses, invert conditions
Effort: M (refactor structure)
3. Long Methods (> 50 lines)
What: Functions too long, doing too much
Detection:
- Count lines between function start and end
- Exclude comments, blank lines
Severity:
- HIGH: > 100 lines
- MEDIUM: 51-100 lines
- LOW: 40-50 lines (borderline)
Recommendation: Split into smaller functions, apply Single Responsibility
Effort: M (extract logic)
4. God Classes/Modules (> 500 lines)
What: Files with too many responsibilities
Detection:
- Count lines in file (exclude comments)
- Check number of public methods/functions
Severity:
- HIGH: > 1000 lines
- MEDIUM: 501-1000 lines
- LOW: 400-500 lines
Recommendation: Split into multiple files, apply separation of concerns
Effort: L (major refactor)
5. Too Many Parameters (> 5)
What: Functions with excessive parameters
Detection:
- Count function parameters
- Check constructors, methods
Severity:
- MEDIUM: 6-8 parameters
- LOW: 5 parameters (borderline)
Recommendation: Use parameter object, builder pattern, default parameters
Effort: S-M (refactor signature + calls)
6. O(n²) or Worse Algorithms
What: Inefficient nested loops over collections
Detection:
- Nested for loops:
for (i) { for (j) { ... } } - Nested array methods:
arr.map(x => arr.filter(...))
Severity:
- HIGH: O(n²) in hot path (API request handler)
- MEDIUM: O(n²) in occasional operations
- LOW: O(n²) on small datasets (n < 100)
Recommendation: Use hash maps, optimize with single pass, use better data structures
Effort: M (algorithm redesign)
7. N+1 Query Patterns
What: ORM lazy loading causing N+1 queries
Detection:
- Find loops with database queries inside
- Check ORM patterns:
users.forEach(u => u.getPosts())
Severity:
- CRITICAL: N+1 in API endpoint (performance disaster)
- HIGH: N+1 in frequent operations
- MEDIUM: N+1 in admin panel
Recommendation: Use eager loading, batch queries, JOIN
Effort: M (change ORM query)
8. Constants Management (NEW)
What: Magic numbers/strings, decentralized constants, duplicates
Detection:
| Issue | Pattern | Example |
|---|---|---|
| Magic numbers | Hardcoded numbers in conditions/calculations | if (status === 2) |
| Magic strings | Hardcoded strings in comparisons | if (role === 'admin') |
| Decentralized | Constants scattered across files | MAX_SIZE = 100 in 5 files |
| Duplicates | Same value multiple times | STATUS_ACTIVE = 1 in 3 places |
| No central file | Missing constants.ts or config.py |
No single source of truth |
Severity:
- HIGH: Magic numbers in business logic (payment amounts, statuses)
- MEDIUM: Duplicate constants (same value defined 3+ times)
- MEDIUM: No central constants file
- LOW: Magic strings in logging/debugging
Recommendation:
- Create central constants file (
constants.ts,config.py,constants.go) - Extract magic numbers to named constants:
const STATUS_ACTIVE = 1 - Consolidate duplicates, import from central file
- Use enums for related constants
Effort: M (extract constants, update imports, consolidate)
Scoring Algorithm
penalty = (critical * 2.0) + (high * 1.0) + (medium * 0.5) + (low * 0.2)
score = max(0, 10 - penalty)
Output Format
Return JSON to coordinator:
Global mode output:
{
"category": "Code Quality",
"score": 6,
"total_issues": 12,
"critical": 1,
"high": 3,
"medium": 5,
"low": 3,
"findings": [...]
}
Domain-aware mode output (NEW):
{
"category": "Code Quality",
"score": 7,
"domain": "orders",
"scan_path": "src/orders",
"total_issues": 8,
"critical": 0,
"high": 2,
"medium": 4,
"low": 2,
"findings": [
{
"severity": "HIGH",
"location": "src/orders/services/OrderService.ts:120",
"issue": "Cyclomatic complexity 22 (threshold: 10)",
"principle": "Code Complexity / Maintainability",
"recommendation": "Split into smaller methods",
"effort": "M",
"domain": "orders"
},
{
"severity": "MEDIUM",
"location": "src/orders/controllers/OrderController.ts:45",
"issue": "Magic number '3' used for order status",
"principle": "Constants Management",
"recommendation": "Extract: const ORDER_STATUS_SHIPPED = 3",
"effort": "S",
"domain": "orders"
}
]
}
Critical Rules
- Do not auto-fix: Report only
- Domain-aware scanning: If
domain_mode="domain-aware", scan ONLYscan_path(not entire codebase) - Tag findings: Include
domainfield in each finding when domain-aware - Context-aware: Small functions (n < 100) with O(n²) may be acceptable
- Constants detection: Exclude test files, configs, examples
- Metrics tools: Use existing tools when available (ESLint complexity plugin, radon, gocyclo)
Definition of Done
- contextStore parsed (including domain_mode and current_domain)
- scan_path determined (domain path or codebase root)
- All 8 checks completed (scoped to scan_path):
- complexity, nesting, length, god classes, parameters, O(n²), N+1, constants
- Findings collected with severity, location, effort, recommendation, domain
- Score calculated
- JSON returned to coordinator with domain metadata
Reference Files
- Code quality rules: references/code_quality_rules.md
Version: 3.0.0 Last Updated: 2025-12-23