tl-complexity-assessment

<!-- Copyright (c) 2026 Todd Levy. Licensed under MIT. SPDX-License-Identifier: MIT -->

tl-complexity-assessment

Find the files that need to be split up. Get a ranked, evidence-based list of complexity hotspots with specific refactoring recommendations.

Quick Start

For experienced users — run the scanner and get a report:

# Bash
./​scripts/​complexity-scan.sh src/

# PowerShell
.\scripts\complexity-scan.ps1 -TargetDir src/

For guided assessment — follow the phases below.

---

When to Use

• "find complex files"
• "what needs to be split up"
• "assess complexity" / "code health check"
• "find monoliths" / "find god files"
• "identify refactoring candidates"
• "this file is too big"
• Before major refactoring efforts
• When onboarding to a new codebase
• Sprint planning for tech debt reduction

Do Not Use When

• Looking for bugs (use debugging skills instead)
• Assessing security vulnerabilities (use security audit)
• Reviewing code style (use linting/​formatting tools)
• File is already small and focused (<150 lines, single responsibility)

Outcomes

• Analysis: Ranked list of complexity hotspots with evidence and recommendations
• Decision: Which files/​modules to refactor first (ROI-based prioritization)
• Artifact: Optional findings register (markdown) for tracking remediation
• Next Steps: Clear refactoring recommendations for each finding

---

The Iron Law

NO COMPLEXITY CLAIMS WITHOUT EVIDENCE

Every finding must include file path, line count or metric, and specific observation.

What Good Looks Like

❌ BAD: "UserService.ts is too complex and should be refactored"

✅ GOOD: "UserService.ts (847 lines, 23 exports) mixes 4 concerns:
   - Authentication (lines 1-150)
   - Validation (lines 151-320)  
   - API calls (lines 321-600)
   - Formatting (lines 601-847)
   
   Recommendation: Split into auth.ts, validation.ts, api.ts, formatters.ts
   Effort: E2 (4-8 hours) | Impact: High (imported by 12 files)"

---

Assessment Categories

Category 1: Size Indicators

Category 2: Responsibility Indicators

Category 3: Coupling Indicators

Category 4: Cyclomatic Complexity Proxies

Category 5: React-Specific Smells

Category 6: Structural Smells

---

Assessment Phases

Phase 1: Automated Discovery

Run these commands to gather metrics. Adapt paths to your project structure.

Find large files:

find src/ -name "*.ts" -o -name "*.tsx" | xargs wc -l 2>/​dev/​null | sort -rn | head -30

Count exports per file:

rg "^export " --type ts -c | sort -t: -k2 -rn | head -20

Count imports per file:

rg "^import " --type ts -c | sort -t: -k2 -rn | head -20

Find god files:

rg -l "utils|helpers|common|shared" --type ts --glob "!node_modules" | head -20

Find React components with many hooks:

rg "useEffect\(" --type tsx -c | sort -t: -k2 -rn | head -20

Find deeply nested conditionals:

rg "if.*if.*if" --type ts -l | head -20

Find files with many functions:

rg "^(export )?(async )?(function |const \w+ = )" --type ts -c | sort -t: -k2 -rn | head -20

Phase 2: Manual Analysis

For each candidate file from Phase 1:

1. Read the file - Understand what it does
2. Identify responsibilities - List distinct concerns
3. Check coupling - What does it import from? What imports it?
4. Assess cohesion - Do all parts serve a single purpose?
5. Document evidence - File path, line count, specific observations

Phase 3: Scoring

Score each finding 0-10:

Score Formula:

Score = (Severity × 2) + (Impact × 2) + (Effort_Inverse)

Where:

• Severity: 1 (Low) to 3 (Critical)
• Impact: 1 (isolated) to 3 (affects many files)
• Effort_Inverse: 3 (easy fix) to 1 (hard fix)

Phase 4: Report

For each finding, report:

### [Rank] File: `path/​to/​file.ts`

**Score:** 8/​10 | **Severity:** High | **Effort:** Medium

**Metrics:**
- Lines: 847
- Exports: 23
- Imports: 18 (from 6 domains)

**Observations:**
- Contains 4 unrelated responsibilities: auth, validation, API calls, formatting
- 3 useEffect hooks managing different concerns
- Imported by 12 other files

**Recommendation:**
Split into:
- `auth.ts` - Authentication utilities
- `validation.ts` - Form validation
- `api.ts` - API client functions
- `formatters.ts` - Display formatting

**Evidence:**
Lines 1-150: Auth functions
Lines 151-320: Validation schemas
Lines 321-600: API calls
Lines 601-847: Formatting utilities

---

Priority Matrix

ROI = Severity × (4 - Effort)

🔥 = Address first (ROI ≥ 9)

---

Red Flags - Stop and Reassess

If you catch yourself:

• Claiming "this file is complex" without metrics
• Recommending splits without identifying responsibilities
• Skipping files because they "look fine"
• Using vague terms like "too big" or "messy"
• Recommending refactors without considering import impact

Return to Phase 1. Gather evidence.

---

Rationalizations (Do Not Skip)

---

Time-Boxing Guidelines

When time expires: Document what you found. Mark incomplete areas with next actions.

---

Output Format

Provide a summary table followed by detailed findings:

## Complexity Assessment Summary

| Rank | File | Score | Severity | Recommendation |
|------|------|-------|----------|----------------|
| 1 | `src/​utils/​helpers.ts` | 9 | Critical | Split into 4 domain files |
| 2 | `src/​components/​Dashboard.tsx` | 8 | High | Extract 3 sub-components |
| 3 | `src/​api/​client.ts` | 7 | High | Separate by API domain |

### Top Finding Details
[Detailed findings for top 5-10 items]

Example Real Output

See Example Output for a worked-through assessment report (summary table, per-file score, observations, recommendations, evidence).

---

What To Do After Assessment

Once you have findings, here's how to act on them:

Immediate (This Sprint)

1. Fix 🔥 Critical findings (ROI ≥ 9) - These block velocity
2. Run tl-knip to remove dead exports before splitting
3. Add tests for files you're about to split

Plan (Next Sprint)

1. Create tickets for High-priority findings (score 7-8)
2. Group related splits (e.g., all API files together)
3. Estimate using the Effort column

Monitor (Ongoing)

1. Re-run assessment monthly to catch new complexity
2. Add complexity checks to PR reviews
3. Set team threshold: "No new files over 300 lines without review"

---

Cognitive vs Cyclomatic Complexity

See Cognitive Complexity for the difference between cyclomatic and cognitive complexity, scoring rules, and ESLint/​SonarJS integration.

---

Code Review Metrics

See Code Review Metrics for optimal PR size thresholds, review time budgets, and a CI complexity-gate workflow example.

---

Verification Checklist

Before completing assessment:

• Ran automated discovery commands
• Every finding has file path and line count
• Every finding has specific observations (not vague)
• Responsibilities identified for each split recommendation
• Effort estimated for each recommendation
• Priority calculated using ROI formula
• Time-boxing respected
• Summary table provided with top findings

---

Skill Resources

Automated Discovery

Run the scanner script for quick assessment:

# Bash
./​scripts/​complexity-scan.sh src/

# PowerShell
.\scripts\complexity-scan.ps1 -TargetDir src/

Reference Documentation

Load these references when deeper analysis is needed for a specific category.

---

Related Skills

• tl-knip - Find unused exports (reduces false positives in export counts)
• codebase-audit - Broader code health assessment
• ui-audit - UI-specific complexity and drift detection
• semgrep/​skills/​code-security - Security vulnerability detection (complementary to structural complexity)

---

References

Quilted Sources

• trailofbits/​skills/​code-maturity-assessor — Assessment framework
• obra/​superpowers/​systematic-debugging — Iron Law pattern
• obra/​superpowers/​verification-before-completion — Evidence principles
• rmyndharis/​antigravity-skills/​code-refactoring-refactor-clean — SOLID assessment

Official Skills

• semgrep/​skills/​semgrep — Static analysis and custom rule creation
• semgrep/​skills/​code-security — Security vulnerability patterns
• jwynia/​agent-skills/​code-review — Review metrics

First-Party Documentation

• ESLint Complexity Rule — Cyclomatic complexity linting
• SonarQube Cognitive Complexity — Cognitive complexity definition
• Semgrep Rule Writing — Custom complexity rules
• TypeScript Compiler API — AST analysis

Academic/​Industry

• Cognitive Complexity Paper — Original SonarSource definition
• Code Complete 2 — McConnell complexity guidance