Cyclomatic Complexity
Purpose: AI-written code often works but branches like a jungle. This skill: measure complexity, refactor hotspots, keep code human-maintainable.
Measure first
CC = decision points + 1. Decision points: if, else if, case, loops, catch, ternary, &&, || in conditions.
Project linter config wins. If eslintrc, radon config, sonar config, or similar sets a complexity threshold, use that. No config: use defaults below.
Thresholds:
- 1-5: fine, leave alone
- 6-10: watch, refactor if touching anyway
- 11-15: refactor now
- 15+: must split, no debate
Prefer real tools over eyeballing when environment allows:
- Python:
radon cc -s -a <path>
- JS/TS: eslint
complexity rule
- Go:
gocyclo
- Polyglot:
lizard <path>
No tool available: count manually, per function, show the count.
Refactor tactics, in order of preference
- Guard clauses. Invert conditions, return early, kill nesting.
- Extract function. Each extracted piece gets a name that says what, not how. Names are documentation.
- Lookup table / map instead of if-else or switch chains.
- Named predicates.
if (isEligibleForRefund(order)) beats a 4-clause boolean soup.
- Polymorphism / strategy for switch-on-type. Only when the switch appears in 2+ places.
- Flatten loops. Extract loop body, use continue instead of nested if.
Hard rules
- Preserve behavior. Run tests before and after. No tests: say so, suggest adding, refactor conservatively.
- Don't game the metric. A dense one-liner hiding 6 branches is worse than the honest if-chain it replaced. Complexity should move into well-named units, not disappear into cleverness.
- Don't break public APIs or exported signatures without asking.
- Small functions with clear names > few functions with comments explaining sections.
- One responsibility per function. If the name needs "and", split.
Workflow
- Measure all touched functions, rank by CC descending.
- Report hotspots with numbers before touching anything.
- Refactor worst first, one function at a time.
- Re-measure. Show before/after table: function, CC before, CC after.
- Verify: tests pass, behavior unchanged, diff reviewable.
Output format
End every refactor with:
## Complexity report
| Function | Before | After |
|----------|--------|-------|
| parseOrder | 14 | 4 |
Extracted: validateHeader, resolveDiscount
Behavior verified: <how>
Keep prose minimal. Numbers and diffs do the talking.