complexity

$27

# Check for Python files

ls *.py **/*.py 2>/dev/null | head -1 && echo "Python detected"

# Check for Go files

ls *.go **/*.go 2>/dev/null | head -1 && echo "Go detected"

Step 3: Run Complexity Analysis

For Python (using radon):

# Check if radon is installed

which radon || pip install radon

# Run cyclomatic complexity

radon cc <path> -a -s

# Run maintainability index

radon mi <path> -s

For Go (using gocyclo):

# Check if gocyclo is installed

which gocyclo || go install github.com/fzipp/gocyclo/cmd/gocyclo@latest

# Run complexity analysis

gocyclo -over 10 <path>

Step 4: Interpret Results

Cyclomatic Complexity Grades:

Grade

CC Score

Meaning

A

1-5

Low risk, simple

B

6-10

Moderate, manageable

C

11-20

High risk, complex

D

21-30

Very high risk

F

31+

Untestable, refactor now

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

# Complexity Report: <Target>

**Date:** YYYY-MM-DD

**Language:** <Python/Go>

**Files Analyzed:** <count>

## Summary

- Average CC: <score>

- Highest CC: <score> in <function>

- Functions over threshold: <count>

## Refactor Targets

### Critical (CC > 20)

| Function | File | CC | Recommendation |

|----------|------|-----|----------------|

| <name> | <file:line> | <score> | <how to simplify> |

### High (CC 11-20)

| Function | File | CC | Recommendation |

|----------|------|-----|----------------|

| <name> | <file:line> | <score> | <how to simplify> |

## Refactoring Recommendations

1. **<Function>**: <specific suggestion>

   - Extract: <what to extract>

   - Simplify: <how to simplify>

## Next Steps

- [ ] Address critical complexity first

- [ ] Create issues for high complexity

- [ ] Consider refactoring sprint

Step 7: Report to User

Tell the user:

• Overall complexity summary

• Number of functions over threshold

• Top 3 refactoring targets

• Location of full report

• 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:

• Agent detects Python files in src/ directory

• Agent checks for radon installation, installs if missing

• Agent runs radon cc src/ -a -s for cyclomatic complexity

• Agent runs radon mi src/ -s for maintainability index

• Agent identifies 3 functions with CC > 20, 7 functions with CC 11-20

• Agent writes detailed report to .agents/complexity/2026-02-13-src.md

• 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:

• Agent checks recent changes with git diff --name-only HEAD~5

• Agent detects Go files, verifies gocyclo installation

• Agent runs gocyclo -over 10 ./... on project

• Agent finds HandleWebhook() function with complexity 34

• Agent writes report with recommendation to extract validation logic

• 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

Problem

Cause

Solution

Tool not installed (radon/gocyclo)

Missing dependency

Agent auto-installs: pip install radon for Python or go install github.com/fzipp/gocyclo/cmd/gocyclo@latest for Go. Verify install path in $PATH.

No complexity issues found

Threshold too high or genuinely simple code

Lower threshold: try gocyclo -over 5 or check if path includes actual implementation files vs tests.

Report shows functions without recommendations

Generic analysis without codebase context

Read the high-CC functions to understand structure, then provide specific refactoring suggestions based on actual code patterns.

Mixed language project

Multiple languages in target path

Run analysis separately per language: /complexity src/python/ then /complexity src/go/, combine reports manually.