Creo Perf

creo-perf — performance optimization with proof

No performance claim without a number. Baseline before touching code, an identical re-measure after, one concern per commit, correctness checked on every pair. The harness makes the numbers deterministic; this skill makes the workflow non-negotiable.

Commands

Harness resolution

The scripts live in the perf-harness extension. Resolve PERF_HARNESS as the first existing of:

1. ${CLAUDE_PLUGIN_ROOT}/extensions/perf-harness (plugin install)
2. ~/.claude/skills/creo-perf-harness (extensions/perf-harness/install.sh)
3. <creo checkout>/extensions/perf-harness

After init, the project wrapper .claude/skills/creo-perf/perf <cmd> [args] resolves it automatically; prefer the wrapper in every Bash call below. If no harness is found, say so and offer the manual protocol from references/measurement-protocol.md — never fabricate numbers.

Configuration

1. Read .claude/project-config.md (project_id, dev_server_url, stack).
2. Load the project extension .claude/skills/creo-perf/creo-perf-{project_id}.md — targets, scenarios, hot-path map, hazards, environment log, findings ledger. It is authoritative; consult it before any work.
3. perf.config.sh in the same directory is the machine-readable twin the scripts read. Keep the two in sync (init writes both; fixes update both).
4. If the extension is missing, run /creo perf init before anything else.

/creo perf init — prepare a project

Goal: after init, perf audit-all before runs end to end without edits.

1. Scaffold: "$PERF_HARNESS/scripts/init-project.sh" [--project-id X] (copies templates, writes the perf wrapper, appends .gitignore).
2. Detect the stack (read, do not guess): package managers, docker-compose*, Dockerfiles, nginx/Caddy configs, backend framework and ORM, frontend bundler, DB engine and connection details, container names, ports. Record the port map and which port bypasses the proxy.
3. Fill perf.config.sh: PERF_API, PERF_PROXY (empty if no proxy), PERF_WEB, PERF_PSQL_CMD (array), containers, PERF_DB_TABLES / PERF_DB_HOT_TABLE, app/backend dirs, build command, PERF_BACKEND_KIND, PERF_SQL_MODE (record for SQLAlchemy/SQLModel apps with a venv, else compile), PERF_ALL_ORDER, hazards. Verify every URL with curl.
4. Propose scenarios from the hot path: read the route handlers the problem statement points at, list the user-facing interactions (default page load, search, each filter, sort, pagination variants, heavy endpoints such as tiles/exports), and write one scenarios/<id>.sh each using scenarios/.template.sh. URLs come from the API docs or the handler signature — never invented. Put the unbounded / cache-churning variants in the scenario that runs last. Follow references/scenario-spec.md.
5. SQL sources: record mode — fill sql-calls.py with one call(...) per scenario mirroring the URLs; compile mode — write sql-src/<runner>/<label>.sql with the statement each handler executes (binds inlined), .rows.sql for row-returning statements. Note which is which in the extension doc.
6. FE probes: fill fe-interactions.json with one entry per interaction scenario (selectors read from the component source; rows = the rendered row selector). Check Playwright resolves from PERF_APP_DIR; if not, say the FE rows will read "unavailable" until it is installed.
7. Dashboard config: dashboard.json order, titles, endpoint -> handler file:line per scenario.
8. Write the extension doc creo-perf-{project_id}.md from the template: stack table, targets, scenario table, hot-path map with file:line, hazards (large files never to open, destructive commands, port collisions, missing env vars), empty environment log and findings ledger.
9. Verify: perf preflight must pass; then run ONE cheap scenario under a throwaway label (perf audit-scenario <id> init-check --runs 3), read its metrics file, fix whatever is empty or wrong, delete the throwaway dir.
10. Summarize what was configured and what stays manual (browser-only layers, stacks without a platform probe).

Ask the user only for facts that cannot be read from the repo (credentials not in compose files, which page is the complaint about, a proxy that only exists in production).

Measurement rules (non-negotiable)

• Baseline BEFORE any code change. A label directory is immutable once written; before is never re-run after a fix lands. New label per re-measure (after-<what>); --force only on non-baseline captures.
• Only script-to-script pairs are comparable. Never derive an ad-hoc number for a before/after claim.
• Identical scenario, environment and commands on both sides; label every number (direct vs proxy, warm vs cold, prod vs dev build, docker vs local).
• Median of >= 3 warm runs plus the first cold hit; never a single run, never averages that hide tails.
• Never run two captures concurrently. Respect PERF_ALL_ORDER.
• Correctness rides along: row counts, filter results, ETag/304 behavior must match before vs after — drift is a regression, not a win.
• Never ANALYZE mid-audit; planner-stats state is itself an observation.
• A config value is never evidence; prove a config change by re-running a scenario and diffing its plan/latency.
• Environment changes (observability enablement, container restarts) go in the extension doc's environment log with the capture that validated them.

Full protocol: references/measurement-protocol.md.

/creo perf baseline

1. Preflight. Confirm the stack is the production-shaped one (proxy in front, prod build served) — a dev server baseline is invalid for proxy/bundle work.
2. perf audit-all <label> (default before). Runtime 15-30 min; do not run anything else against the stack meanwhile.
3. Verify the run ended with dashboard: .../results/dashboard.md and that every scenario has a column. Read each <id>-metrics.md; any n/a, missing, or unavailable cell is fixed now (scenario file, SQL source, Playwright) and that scenario re-captured under the same label with --force — the baseline is still pre-fix, so this is legitimate.
4. Commit results/dashboard.md and the project extension.

/creo perf audit

Spawn creo-perf-audit via the Agent tool with context: fork, passing the mode (baseline | after | discover), the label(s), and the scope (which page / flow). It measures and ranks; it never edits application code. Relay its findings ranked by severity with the evidence index. Do not re-run the harness yourself while it is running.

/creo perf optimize — the fix loop

One finding at a time, top severity first unless the user picks one.

1. Read the evidence: the finding's scenario metrics and the decisive plan or trace lines. Attribute the cost to one layer with that layer's profiler; do not claim a cause measured at another layer.
2. Design the smallest fix at that layer. Prefer: unindexable predicate -> sargable rewrite + index; duplicate aggregates -> one query; oversized payload -> trim to what the UI reads; missing compression / caching headers at the edge; refetch storms -> query-client config; blank-on-refetch -> placeholder data; eager heavy libs -> route-level lazy boundaries; per-row render work -> virtualization. See references/layer-audit-checklists.md.
3. Implement one concern. Keep the harness aligned: if the fix changes a query shape, update sql-calls.py / sql-src and the scenario's expected sections in the same change so the after-capture measures the real thing.
4. Re-measure: perf audit-scenario <id> after-<what> for every scenario the fix touches (fe for bundle/edge work; platform/schema when config or indexes changed). Never re-run before.
5. Verify: dashboard delta on the headline metric; correctness refs identical; no other scenario regressed (re-capture a neighbor if the fix could affect it). A regression or drift blocks the commit.
6. Record: append a row to the findings ledger in the extension doc (scenario, layer, bottleneck, fix, before -> after, commit); update the hot-path map if files moved.
7. Commit one concern: perf(<layer>): <what> — <headline before -> after>, body with the decisive evidence and the labels compared. Include the updated dashboard.md and harness config in the same commit.
8. Repeat. Stop when remaining findings are Low or the user's target is met.

/creo perf report

Produce the deliverable write-up (SOLUTION.md-style) per finding: bottleneck -> profiling proof (plan/trace excerpt, numbers, labels) -> fix (files, mechanism) -> before/after table from the dashboard -> commit. Use references/report-templates.md. Numbers are copied from results/dashboard.md, never retyped from memory.

Layers

Checklists per layer: references/layer-audit-checklists.md. Top-down triage, bottom-up proof.

Reference files

Quality gates

• Every claim in a report maps to a dashboard cell or an archived raw file.
• Before/after pairs share scenario, environment, and script version.
• Correctness references identical across the pair.
• Findings ledger and dashboard committed with each perf commit.
• No emojis in generated files; kebab-case scenario ids; stable metric names.