perf-profile

When this skill is invoked:

1. Determine scope from the argument:
2. If a system name: focus profiling on that specific system
3. If full: run a comprehensive profile across all systems

1. Read performance budgets — Check for existing performance targets in design docs or CLAUDE.md:
2. Target FPS (e.g., 60fps = 16.67ms frame budget)
3. Memory budget (total and per-system)
4. Load time targets
5. Draw call budgets
6. Network bandwidth limits (if multiplayer)

1. Analyze the codebase for common performance issues:

CPU Profiling Targets:

• _process() / Update() / Tick() functions — list all and estimate cost
• Nested loops over large collections
• String operations in hot paths
• Allocation patterns in per-frame code
• Unoptimized search/sort over data entities
• Expensive physics queries (raycasts, overlaps) every frame

Memory Profiling Targets:

• Large data structures and their growth patterns
• Texture/asset memory footprint estimates
• Object pool vs instantiate/destroy patterns
• Leaked references (objects that should be freed but aren't)
• Cache sizes and eviction policies

Rendering Targets (if applicable):

• Draw call estimates
• Overdraw from overlapping transparent objects
• Shader complexity
• Unoptimized particle systems
• Missing LODs or occlusion culling

I/O Targets:

• Save/load performance
• Asset loading patterns (sync vs async)
• Network message frequency and size

1. Generate the profiling report:

```markdown ## Performance Profile: [System or Full] Generated: [Date]

### Performance Budgets | Metric | Budget | Estimated Current | Status | |--------|--------|-------------------|--------| | Frame time | [16.67ms] | [estimate] | [OK/WARNING/OVER] | | Memory | [target] | [estimate] | [OK/WARNING/OVER] | | Load time | [target] | [estimate] | [OK/WARNING/OVER] | | Draw calls | [target] | [estimate] | [OK/WARNING/OVER] |

### Hotspots Identified | # | Location | Issue | Estimated Impact | Fix Effort | |---|----------|-------|------------------|------------| | 1 | [file:line] | [description] | [High/Med/Low] | [S/M/L] | | 2 | [file:line] | [description] | [High/Med/Low] | [S/M/L] |

### Optimization Recommendations (Priority Order)

1. [Title] — [Description of the optimization]
2. Location: [file:line]
3. Expected gain: [estimate]
4. Risk: [Low/Med/High]
5. Approach: [How to implement]

### Quick Wins (< 1 hour each)

• [Simple optimization 1]
• [Simple optimization 2]

### Requires Investigation

• [Area that needs actual runtime profiling to determine impact]

```

1. Output the report with a summary: top 3 hotspots, estimated headroom vs budget, and recommended next action.

Rules

• Never optimize without measuring first — gut feelings about performance are unreliable
• Recommendations must include estimated impact — "make it faster" is not actionable
• Profile on target hardware, not just development machines
• Distinguish between CPU-bound, GPU-bound, and I/O-bound bottlenecks
• Consider worst-case scenarios (maximum entities, lowest spec hardware, worst network conditions)
• Static analysis (this skill) identifies candidates; runtime profiling confirms

Protocol

• Question: Reads system name or full from argument
• Options: Skip
• Decision: Skip
• Draft: Profile report shown in conversation only
• Approval: Skip — read-only; no files written by default

Output

Deliver exactly:

• Top 3 hotspots — system, estimated impact, and recommended fix
• Budget headroom — actual vs target for each metric in technical-preferences.md
• Optimization priority list — ranked by impact/effort ratio
• Next action: PROFILE CONFIRMED (static analysis sufficient) or RUNTIME PROFILING NEEDED (list what to measure)