Complexity Analysis

Analyze code complexity, distinguishing accidental from essential complexity, with actionable recommendations.

Definitions

Accidental complexity: Complexity from implementation choices, not the problem itself. Examples: unnecessary abstractions, over-engineering, redundant code, poor naming, convoluted control flow.

Essential complexity: Inherent to the problem domain. Cannot be eliminated, only managed. Examples: business rules, domain logic, regulatory requirements, algorithmic constraints.

Workflow

1. Scope Identification

Determine target:

• Single file: analyze that file

• Directory/module: identify key files, analyze each, then synthesize

2. Analysis Process

For each code unit:

• Read and understand the code's purpose

• Identify accidental complexity:

• Unnecessary abstractions/indirection

• Code duplication

• Over-engineering (features not needed)

• Poor separation of concerns

• Convoluted logic that could be simplified

• Inconsistent patterns

• Dead code

• Identify essential complexity:

• Core business logic

• Domain rules that must exist

• Algorithmic requirements

• External constraints (APIs, protocols)

3. Recommendations

For accidental complexity:

• Recommend elimination or reduction

• Provide concrete refactoring suggestions

• Estimate effort (low/medium/high)

For essential complexity:

• Recommend isolation strategies

• Suggest simplification approaches

• Propose robustness improvements

• Identify testing strategies

4. Priority Assignment

Assign priority (P0-P3) based on:

• P0 (Critical): Blocks development, causes bugs, high maintenance burden

• P1 (High): Significant impact on readability/maintainability

• P2 (Medium): Moderate improvement opportunity

• P3 (Low): Minor enhancement, nice-to-have

5. Report Generation

Write report to complexity-report.md in cwd.