perf-profile

name	perf-profile
description	Structured performance profiling workflow. Identifies bottlenecks, measures against budgets, and generates optimization recommendations with priority rankings. Game: CPU/GPU/frame-time. Product: API latency, DB queries, memory, throughput.
argument-hint	[system-name or 'full']
user-invocable	true
agent	performance-analyst
allowed-tools	Read, Glob, Grep, Bash

User Guide

• When to use: Structured performance profiling workflow. Identifies bottlenecks, measures against budgets, and generates optimization recommendations with priority rankings. Game: CPU/GPU/frame-time. Product: API latency, DB queries, memory, throughput.
• Inputs: Command arguments: /perf-profile [system-name or 'full']; project artifacts referenced below; user decisions and approvals before writes.
• Outputs: Primary artifacts, reports, or conversation guidance described below; write files only after user approval.
• Memory-bank writes: None.
• Next steps: Follow the workflow hand-off or next-step guidance below; recommendations do not auto-run and require explicit user command/approval.

Phase 0: Domain Detection

Detect the project domain by checking for concept documents in design/cdd/:

• Game: design/cdd/game-concept.md exists → use [Game] paths below
• Product: design/cdd/product-concept.md exists → use [Product] paths below
• Neither: default to game paths (preserves backward compatibility)

---

Phase 1: Determine Scope

Read the argument:

• System name → focus profiling on that specific system
• full → run a comprehensive profile across all systems

---

Phase 2: Load Performance Budgets

Check for existing performance targets in design docs or CLAUDE.md.

[Game] Performance budgets:

• Target FPS (e.g., 60fps = 16.67ms frame budget)
• Memory budget (total and per-system)
• Load time targets
• Draw call budgets
• Network bandwidth limits (if multiplayer)

[Product] Performance budgets:

• API latency (p50/p95/p99 targets)
• Memory budget (total and per-service)
• Cold start time target
• Throughput (requests/sec, events/sec)
• Database query time budget
• Network bandwidth limits (if applicable)

---

Phase 3: Analyze Codebase

[Game] Game Profiling Targets

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 game 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

[Product] Product Profiling Targets

API Profiling Targets:

• Endpoint handlers — list all and estimate latency
• Middleware chain cost (auth, logging, validation)
• Serialization/deserialization overhead (JSON, protobuf)
• N+1 query patterns in request handlers
• Unbounded result sets (missing pagination)

Database Profiling Targets:

• Missing indexes on query WHERE/JOIN columns
• Slow queries (full table scans, unoptimized joins)
• Connection pool utilization and wait time
• Transaction scope (too broad = lock contention)

Memory Profiling Targets:

• Large in-memory caches without eviction policies
• Unbounded collections (growing lists, maps)
• Memory retained across requests (stateful singletons)
• Leaked connections (database, HTTP, message queue)

I/O Targets:

• Blocking I/O on async/event-loop threads
• File read/write patterns (buffer sizes, streaming vs full load)
• Network call timeout and retry configuration
• Third-party API call latency and failure modes

---

Phase 4: Generate Profiling Report

[Game] Game Profiling Report

## 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 |
|---|----------|-------|------------------|------------|

### Optimization Recommendations (Priority Order)
1. **[Title]** — [Description]
   - Location: [file:line]
   - Expected gain: [estimate]
   - Risk: [Low/Med/High]
   - Approach: [How to implement]

### Quick Wins (< 1 hour each)
- [Simple optimization 1]

### Requires Investigation
- [Area that needs actual runtime profiling to confirm impact]

[Product] Product Profiling Report

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

### Performance Budgets
| Metric | Budget | Estimated Current | Status |
|--------|--------|-------------------|--------|
| API latency (p95) | [target] | [estimate] | [OK/WARNING/OVER] |
| Memory (RSS) | [target] | [estimate] | [OK/WARNING/OVER] |
| Cold start | [target] | [estimate] | [OK/WARNING/OVER] |
| Throughput | [target] | [estimate] | [OK/WARNING/OVER] |
| DB query time (p95) | [target] | [estimate] | [OK/WARNING/OVER] |

### Hotspots Identified
| # | Location | Issue | Estimated Impact | Fix Effort |
|---|----------|-------|------------------|------------|

### Optimization Recommendations (Priority Order)
1. **[Title]** — [Description]
   - Location: [file:line]
   - Expected gain: [estimate]
   - Risk: [Low/Med/High]
   - Approach: [How to implement]

### Quick Wins (< 1 hour each)
- [Simple optimization 1]

### Requires Investigation
- [Area that needs actual runtime profiling to confirm impact]

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

---

Phase 5: Scope and Timeline Decision

Activate this phase only if any hotspot has Fix Effort rated M or L.

Present significant-effort items and ask the user to choose for each:

• A) Implement the optimization (proceed with fix now or schedule it)
• B) Reduce feature scope (run /scope-check [feature] to analyze trade-offs)
• C) Accept the performance hit and defer to Polish phase (log as known issue)
• D) Escalate to technical-director for an architectural decision (run /architecture-decision)

[Game] If multiple items are deferred to Polish (choice C), record them under ### Deferred to Polish. [Product] If multiple items are deferred (choice C), record them under ### Deferred Performance Items.

This skill is read-only — no files are written. Verdict: COMPLETE — performance profile generated.

---

Phase 6: Next Steps

• If bottlenecks require architectural change: run /architecture-decision.
• If scope reduction is needed: run /scope-check [feature].
• To schedule optimizations: run /sprint-plan update.

Rules

• Never optimize without measuring first — gut feelings about performance are unreliable
• Recommendations must include estimated impact — "make it faster" is not actionable
• [Game] Profile on target hardware, not just development machines
• [Product] Profile under realistic load, not just single-request benchmarks
• Static analysis (this skill) identifies candidates; runtime profiling confirms