complexity

Complexity Skill

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Analyze code complexity to identify refactoring targets.

Execution Steps

Given /complexity [path]:

Step 1: Determine Target

If path provided: Use it directly.

If no path: Use current directory or recent changes:

git diff --name-only HEAD~5 2>/dev/null | grep -E '\.(py|go)$' | head -10

Step 2: Detect Language

# Check for Python files
ls *.py **/*

Step 3: Run Complexity Analysis

For Python (using radon):

For Go (using gocyclo):

Step 4: Interpret Results

Cyclomatic Complexity Grades:

Step 5: Identify Refactor Targets

List functions/methods that need attention:

• CC > 10: Should refactor
• CC > 20: Must refactor
• CC > 30: Critical, immediate action

Step 6: Write Complexity Report

Write to: .agents/complexity/YYYY-MM-DD-<target>.md

Step 7: Report to User

Tell the user:

1. Overall complexity summary
2. Number of functions over threshold
3. Top 3 refactoring targets
4. Location of full report
5. Run /refactor <function> to address critical complexity targets

Key Rules

• Use the right tool - radon for Python, gocyclo for Go
• Focus on high CC - prioritize 10+
• Provide specific fixes - not just "refactor this"
• Write the report - always produce artifact

Quick Reference

Simplifying High Complexity:

• Extract helper functions
• Replace conditionals with polymorphism
• Use early returns
• Break up long functions
• Simplify nested loops

Examples

Analyzing Python Project

User says: /complexity src/

What happens:

1. Agent detects Python files in src/ directory
2. Agent checks for radon installation, installs if missing
3. Agent runs radon cc src/ -a -s for cyclomatic complexity
4. Agent runs radon mi src/ -s for maintainability index
5. Agent identifies 3 functions with CC > 20, 7 functions with CC 11-20
6. Agent writes detailed report to .agents/complexity/2026-02-13-src.md
7. Agent recommends extracting nested conditionals in process_request() function

Result: Complexity report identifies process_request() (CC: 28) as critical refactor target with specific extraction recommendations.

Finding Refactor Targets in Go Module

User says: /complexity

What happens:

1. Agent checks recent changes with git diff --name-only HEAD~5
2. Agent detects Go files, verifies gocyclo installation
3. Agent runs gocyclo -over 10 ./... on project
4. Agent finds HandleWebhook() function with complexity 34
5. Agent writes report with recommendation to extract validation logic
6. Agent reports top 3 targets: HandleWebhook (34), ProcessBatch (22), ValidateInput (15)

Result: Critical function identified for immediate refactoring with actionable extraction plan.

See Also

• refactor — Safe, verified refactoring for complexity targets

Troubleshooting

Reference Documents

• references/complexity.feature [blocked] — Executable spec: rank functions by cyclomatic complexity, scope to recent changes by default, focused hotspot list (soc-qk4b)