/perf-profile

name: perf-profile
description: "Performance profiling — find bottlenecks, measure against budgets, produce ranked optimization recommendations."
argument-hint: "[system-name or 'full']"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash(bash "*/.claude/skills/perf-profile/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash "*/.claude/skills/perf-profile/../../hooks/yaml-helper.sh" get_effective_yaml_key *)
model: sonnet

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys performance.enforce,automation,workflow`

Resolved above — use as-is. No block → defaults in `.claude/docs/config-resolution.md`.

Performance Profile

Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md` (collaborative asks always · guided major-only · autonomous logs and proceeds; `automation_always_ask` categories always prompt).

Insufficient input — check this before producing any report

**If the inputs this skill needs do not exist, the answer is "could not run" — not a filled-in report.** Check first, and stop if the check fails.

1. List the inputs this skill reads (data files, prior reports, profiler output, test results, registries, source code). 2. For each, record `FOUND` or `ABSENT` — not "assumed present". 3. If any input required for a section is ABSENT, that section is **`NOT ASSESSED — NO DATA`**. Do not estimate it, do not infer it from an adjacent artifact, and do not leave a mandated cell to be filled by whoever reads the template next. 4. If **every** required input is ABSENT, stop and report **`NOT ASSESSED — NO DATA`** as the whole verdict, naming what was missing and which skill produces it.

**A verdict of `NOT ASSESSED` is a success.** It is the correct, useful answer to "what does the data say?" when there is no data. The failure mode this prevents is specific: a report whose verdict enum has no "could not run" state produces **false clean passes** — an asset audit returning COMPLIANT on a project with no assets and no standards, or a performance profile reporting ">99% headroom against a 16.67ms budget" with zero profiler data and no budget ever set.

**Absence of evidence is never evidence of absence.** A scan that finds no matches because there are no files to scan has not verified anything. Say which of the two happened — a reader cannot tell from a green result.

---

Phase 0: Resolve Budget Enforcement

`performance.enforce` decides what a budget violation *means* in this run. It does not change which budgets are measured — `performance.target_framerate`, `frame_budget_ms`, `draw_call_limit` and `memory_ceiling_mb` are profiled the same way at every level:

| Value | Effect on this profile's findings | |-------|-----------------------------------| | `warn` (default) | Violations are reported as findings. They do not block; CI logs them without failing. | | `block` | Violations are **blockers**. Say so explicitly in the report — a `block` project treats an over-budget system as release-stopping, and `/gate-check` will FAIL the Polish gate on it. | | `off` | Budgets are informational only. Still report measured values, but do not raise violations as findings or recommendations to fix. |

Only `warn`, `block` and `off` are recognized. Surface any other value to the user and fall back to `warn` rather than guessing.

> The value is locally overridable (`/project-settings --local performance.enforce=block`), > so use the resolved block above rather than reading `project.yaml` — a > teammate's stricter local setting is meant to bite on their machine only.

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

**Read the committed budgets from config first** — they are the project's record of what it agreed to, and design docs are the fallback, not the source:

bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" get_effective_yaml_key performance.target_framerate
bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" get_effective_yaml_key performance.frame_budget_ms
bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" get_effective_yaml_key performance.draw_call_limit
bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" get_effective_yaml_key performance.memory_ceiling_mb

Run each line as its own plain command, one key per call: the helper moves to the project root itself, so it works when the session was started in a subfolder, and this skill pre-approves that form only (a `source` or `cd ... &&` wrapper asks the user every time). Empty output means that budget is not set.

> **Resolve these budgets from `project.yaml`, not from prose.** Phase 0 above > states these four budgets "are profiled the same way at every level". A user > who set `performance.target_framerate: 60` in `project.yaml` has it ignored if > the budget is read from design docs or CLAUDE.md instead.

Then fall back to design docs or CLAUDE.md for anything config does not carry:

• 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)

**A metric with no committed budget is `NOT ASSESSED`, not a pass.** Do not measure against the template's `[16.67ms]` placeholder — an unset budget is not a budget that was met, and reporting headroom against a number nobody chose is the exact fabrication this skill's own header warns about.

---

Phase 3: Analyze Codebase

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