Complexity Optimizer

Complexity Optimizer

Find algorithmic complexity hotspots in a codebase and produce a structured report. Optionally implement low-risk optimizations after explicit consent.

When to Apply

Use this skill when the user asks to:

• Analyze, audit, scan, or review a codebase for performance hotspots or algorithmic complexity
• Find inefficient loops, nested iteration, N+1 queries, sort-in-loop, render-path recomputation
• Reduce complexity (e.g. O(n^2) → O(n log n) or O(n))
• "Give me a report" on a codebase's complexity profile

Do not use this skill for:

• Micro-optimizations on cold code paths
• Memory tuning (this skill targets time complexity, not allocation profiles)
• Code style refactoring unrelated to complexity

Workflow Overview

Baseline → Rank → Prove behavior → Optimize (opt-in) → Verify
   ↓           ↓                       ↓
 scanner   prioritize hot          rollback if
 + manual  paths & large I/O       tests regress

Core Rule

Optimize only when current behavior is understood and can be preserved. Prefer a small, proven improvement with tests over a broad rewrite with unclear correctness.

Default Behavior

When the user asks to analyze, scan, audit, review, or "give me a report" for a codebase, produce the full complexity report automatically. Do not require the user to specify report fields.

Default report contents (see references/report-template.md):

• Scope analyzed and detected stack/test commands
• Top findings ranked by likely impact
• File and line for each finding
• Current pattern and why it may be costly
• Estimated current complexity
• Recommended change and estimated complexity after
• Risk level
• Tests, benchmarks, or manual checks needed
• Clear statement that no files were modified, unless the user explicitly requested implementation

Only edit files when the user uses an explicit edit verb: implement, fix, optimize, apply, change, refactor. If the request is analysis-only or a report-only request, do not modify files.

Workflow Detail

1. Baseline

• Identify language, framework, test command, build command, and performance-sensitive paths.
• Inspect existing tests before touching code.
• Run python3 scripts/analyze_complexity.py <repo> for a first-pass hotspot list when scanning a repository.

2. Rank

• Prioritize hot paths, large-input paths, rendering loops, database/API loops, shared utilities.
• Separate algorithmic complexity from constant-factor cleanup.
• Treat scanner output as leads, not proof.
• For report-only requests, inspect enough surrounding code to estimate current and proposed complexity. Do not stop at raw scanner output.

3. Prove behavior

• Locate or add focused tests for the function/component being changed.
• Capture edge cases: empty input, duplicates, ordering stability, null/missing values, errors, permissions, pagination, time zones, mutation side effects.
• If tests are absent and behavior is ambiguous, make the smallest possible refactor or ask for expected behavior before changing semantics.

4. Optimize (only on explicit request)

• Replace repeated linear lookup with maps/sets when key equality is stable.
• Replace nested scans with indexing, grouping, two-pointer scans, sweep-line logic, binary search, memoization, batching, or precomputation — only when the data shape supports it.
• In UI code, reduce unnecessary renders with stable props, memoized derived data, virtualization, debounced work, and moving expensive work out of render paths.
• In data access code, remove N+1 with bulk fetches, joins, preloading, caching, or batching while preserving authorization and filtering.

5. Verify

• Run relevant tests and type/lint/build commands.
• Add a micro-benchmark or measurement when the complexity improvement is non-obvious or performance-critical.
• Report original complexity, new complexity, files changed, tests run, and any residual risk.