Performance Profiler

Analysis-based performance review. Every recommendation grounded in evidence. 6-mode pipeline: Analyze, Profile, Cache, Benchmark, Regression, Leak-Patterns.

Scope: Performance analysis and recommendations only. NOT for running profilers, executing load tests, infrastructure monitoring, or actual memory leak detection. This skill provides analysis-based guidance, not measurements.

Canonical Vocabulary

Use these terms exactly throughout all modes:

Dispatch

Mode 1: Analyze

Algorithmic complexity analysis for files or functions.

Analyze Step 1: Scan

Run the complexity estimator script:

uv run python skills/performance-profiler/scripts/complexity-estimator.py <path>

Parse JSON output. If script fails, perform manual AST-level analysis.

Analyze Step 2: Classify

For each function in scope:

1. Identify loop nesting depth, recursion patterns, data structure operations
2. Map to Big-O classification using references/complexity-patterns.md
3. Score hotspot risk: nesting depth * call frequency * data size sensitivity
4. Flag functions with O(n^2) or worse in hot paths

Analyze Step 3: Report

Present findings as a table:

Include trade-off analysis for each recommendation.

Mode 2: Profile

Interpret textual profiler output pasted by the user.

Profile Step 1: Parse

Run the profile parser script on user-provided data:

uv run python skills/performance-profiler/scripts/profile-parser.py --input <file>

If data is inline, save to temp file first. Parse JSON output.

Profile Step 2: Identify Hotspots

From parsed data:

1. Rank functions by cumulative time (top 10)
2. Identify functions with high call count but low per-call time (overhead candidates)
3. Identify functions with low call count but high per-call time (optimization candidates)
4. Check for I/O-bound vs CPU-bound patterns (wall time vs CPU time ratio)

Profile Step 3: Recommend

For each hotspot, provide:

• Root cause hypothesis with evidence from the profiler data
• Optimization approach with expected impact range
• Trade-offs and risks of the optimization
• Reference to relevant anti-patterns from references/anti-patterns.md

Mode 3: Cache

Design caching strategies for a described system.

Cache Step 1: Understand Access Patterns

Ask about or infer from code:

1. Read/write ratio
2. Data freshness requirements (TTL tolerance)
3. Cache size constraints
4. Consistency requirements (eventual vs strong)
5. Eviction pressure (working set vs cache capacity)

Cache Step 2: Design Strategy

Use references/caching-strategies.md decision tree:

Cache Step 3: Specify

Deliver: eviction policy, write policy, invalidation strategy, warm-up approach, monitoring recommendations. Include capacity planning formula.

Mode 4: Benchmark

Design benchmarks and review methodology.

Benchmark Step 1: Generate Skeleton

Run the benchmark designer script:

uv run python skills/performance-profiler/scripts/benchmark-designer.py --function <signature> --language <lang>

Parse JSON output for setup code, benchmark code, iterations, warmup.

Benchmark Step 2: Review Methodology

Validate against benchmark best practices:

1. Warmup period sufficient to stabilize JIT/caches
2. Iteration count provides statistical significance
3. Measurement excludes setup/teardown overhead
4. Environment controlled (no interference from other processes)
5. Results include variance/percentiles, not just mean

Benchmark Step 3: Deliver

Provide complete benchmark code with methodology notes, expected metrics, and interpretation guide.

Mode 5: Regression

Assess performance regression risk from a code diff.

Regression Step 1: Collect Diff

If path provided, read the diff. If git range provided, run git diff. Identify changed functions and their call sites.

Regression Step 2: Assess Risk

For each changed function:

Risk score = sum of (weight * severity). Map to LOW/MEDIUM/HIGH/CRITICAL.

Regression Step 3: Report

Present regression risk matrix with:

• Per-function risk assessment with evidence
• Aggregate risk score for the diff
• Recommended benchmark targets before merging
• Specific measurements to validate (what to profile and where)

Mode 6: Leak-Patterns

Scan for common memory leak patterns. Static analysis only -- NOT actual leak detection.

Leak Step 1: Scan

Read target files and check against patterns in references/leak-patterns.md:

• Event listener accumulation without cleanup
• Closure-captured references preventing GC
• Growing collections without bounds (unbounded caches, append-only lists)
• Circular references in reference-counted languages
• Resource handles not closed (files, connections, cursors)
• Global state accumulation

Leak Step 2: Classify

For each potential leak pattern found:

Leak Step 3: Report

Present findings with code citations, explain why each pattern risks leaking, and suggest fixes. Acknowledge that static analysis has high false positive rates -- recommend actual profiling tools for confirmation.

Scaling Strategy

Reference Files

Load ONE reference at a time. Do not preload all references into context.

Data Files

Critical Rules

1. Never claim to measure performance — this skill provides analysis, not measurement
2. Every recommendation must include trade-offs — no "just do X" advice
3. Always acknowledge uncertainty in complexity estimates — static analysis has limits
4. Never recommend premature optimization — confirm the code is actually on a hot path first
5. Profiler output interpretation must cite specific data points, not general principles
6. Cache strategy recommendations must address invalidation — "cache invalidation is hard" is not a strategy
7. Benchmark designs must include warmup, statistical significance, and variance reporting
8. Regression risk assessment must trace to specific code changes, not general concerns
9. Leak pattern scanning is pattern-matching only — always recommend actual profiling for confirmation
10. Load ONE reference file at a time — do not preload all references into context
11. Present findings with evidence before suggesting fixes (approval gate)
12. Anti-pattern findings require code citation [file:line] — no generic warnings