Run any Skill in Manus with one click

perf

Stars7

Forks1

UpdatedJuly 22, 2026 at 13:16

Use when measuring, claiming, or investigating anything about render performance — before AND after any renderer/shader/perf change, or when asked "why is this slow?". Runs the headless GPU-timing harness and interprets it correctly.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

rulkens

rulkens/skymap

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

name	perf
description	Use when measuring, claiming, or investigating anything about render performance — before AND after any renderer/shader/perf change, or when asked "why is this slow?". Runs the headless GPU-timing harness and interprets it correctly.

/perf — measure, don't eyeball

npm run perf gives per-pass GPU medians at fixed camera poses in headless Chromium. Any statement like "this pass is expensive", "my change made it faster", or "that's probably fill-bound" should come from a harness run, not intuition. Full reference: tools/perf/README.md.

Procedure

Find your dev server's real port. The harness needs a running dev server (/dev skill) and measures whatever that server serves. In a worktree Vite auto-increments past 5173 — read the Local: line of your npm run dev and pass it explicitly:
```
npm run perf -- --url http://localhost:<port> --scenario <name> --frames 30
```
Omitting --url in a worktree silently measures whichever branch owns 5173.
Baseline BEFORE touching code. Run the scenarios covering the regime you're about to change (earth-surface/solar-system for NEAR0 bodies+stars, star-field/milky-way for the star ladder, local-group/full-survey for survey/COSMO). Save the output to a scratchpad file — you cannot reconstruct the "before" after editing.
Re-run AFTER, same flags. Compare MERGED medians. Run-to-run noise is ~0.5 ms at 30 frames — deltas inside that are not a result; raise --frames for finer claims.
Classify before optimizing. --sweep fits time-vs-pixel-count per pass: exponent ≈1 → fragment/fill-bound (resolution levers help), ≈0 → vertex/CPU-bound (they won't). For data-scale costs use --tier large or --compare-tiers.

Interpretation rules (these get misquoted)

Quote MERGED numbers. That's the production encode shape; TOTAL (merged) + its fps ceiling is the headline (GPU passes only — excludes CPU/present/vsync).
Never quote PER-LAYER rows as real costs. Each carries a fixed ~1–3 ms per-pass overhead (full-viewport DRAM round-trip under the instrumented strategy). Use the EST. PER-PASS FLOOR section's floor-subtracted "real" values for attribution. (orbit-trails/body-glints once read 3–4 ms per-layer; they're ~1 ms real.)
Machine parsing: npm run -s perf -- --json — the -s is required or npm's banner pollutes stdout.
CRITICAL on Apple Silicon: MERGED slot-sums are ~3× inflated. TBDR executes passes concurrently, so back-to-back small passes each report the shared retire interval. The tell: adjacent slots with IDENTICAL medians (e.g. hdr→swap / swap·COSMO / swap·NEAR0 all reading 3.2–3.3 ms). Per-slot ms are ordinal at best: never additive, never fps-convertible. The honest total is a wall-clock/rAF probe: boot ?perf, setStrategy('merged'), setPose to the harness pose, collect 240 rAF deltas, then collectTimings and compare. Sustained 120 fps bounds real per-frame GPU work at ≤ 8.3 ms, whatever the slot sums claim.

Off-harness techniques

Paired-baseline A/B. For before/after claims that survive thermal drift: check out the base commit in a scratch worktree (git worktree add --detach <scratch> <base>), symlink node_modules and public/data into it, start a second dev server (Vite auto-increments the port), and alternate runs A-B-A-B across the two URLs instead of measuring all-A then all-B. Remove the scratch worktree after use.
CPU-side frame costs. Bench against the REAL .bin with a tsx scratchpad script that drives the actual code path (name it .mts: the scratchpad has no package.json, so a plain .ts/.js script runs as CJS). "GC churn" diagnoses are usually inline allocation + cache pressure in disguise; measure before optimizing.

Gotchas

Boot timeout + 504 Outdated Optimize Dep in the page errors → the long-running Vite server went stale under a branch switch or new imports. Restart the dev server, re-run.
After editing shaders/renderers, confirm the server picked the change up (HMR line in its output, or restart) before trusting an "after" run.
Scenario poses live in tools/perf/perfScenarios.ts (captured via the in-app l key). Don't drift them — cross-commit comparability is the harness's whole value.

More from this repository

same repository

refactor-ground

rulkens/skymap

Use when a feature substantial enough for a spec/plan has converged in brainstorming and the spec is about to be written — or standalone, when the user asks "I'm about to add X, what should move first?". Triggers like "/refactor-ground", "add <capability>" (a new source, layer, effect, POI category, tour primitive, settings group), or any ask where existing structure must grow to host new functionality. Skymap-specific; complements entanglement-radar (finds existing knots) — this asks whether the joints the feature needs exist at all.

2026-07-227

refactor

rulkens/skymap

Use when performing a mechanical code refactor in skymap. Rename a symbol repo-wide, extract a symbol into its own file, inline or delete a passthrough wrapper, find who uses a symbol, or move/reorganize `.ts`/`.tsx` files. Triggers like "/refactor", "rename this function everywhere", "extract X into its own file", "inline this wrapper", "delete this unused helper", "who uses this symbol", "move X to Y", "rename this file", "update all the imports", "reorganize the utils folder", "shift these renderers into a subfolder", "folder reorg".

2026-07-217

add-data-source

rulkens/skymap

Use when adding a new data source or featured category to skymap — a new survey catalog feeding the point cloud, or (the common case) a new featured structure category / POI type rendered as marker rings + labels (cluster / supercluster / void / group are the existing four). Triggers like "add a data source", "add a new structure category", "add galaxy groups / walls / a new POI layer", "wire up a new survey". Maps the full edit surface so no parallel site is missed.

2026-07-177

feature-done

rulkens/skymap

Audit a plan against the Definition-of-Done gate before marking it complete. Use when the user types `/feature-done`, asks to "verify the plan is done", "check DoD on <plan>", or is about to close out a feature. Runs the static checks (tests, typecheck, TODO scan, modified-file inventory) and reports a pass/fail summary so unfinished business doesn't get rubber-stamped.

2026-07-177

create-component

rulkens/skymap

Create OR change a React component in `src/components/` following skymap's conventions — own folder, `<Name>.tsx` + `<Name>.module.css`, single-component-per-file, `function Name() {}` + `export default Name`, top-level `.root` class, shared vocabulary in a minimal shared module via `composes` (never `:global`). Use when the user types `/create-component`, asks to "make a component", "add a component", "extract this into a component", or "split this component up" — and, just as important, load it BEFORE editing, refactoring, restructuring, or restyling ANY existing `src/components/**` file (changing its props, markup, exports, or CSS), to check the change against the conventions. Also use proactively whenever a component file is growing past ~120 lines or starts handling more than one concern — the *right* time to create a new component is before the parent gets messy, not after.

2026-07-147

tour

rulkens/skymap

Author or tune a beat of the grand tour ("The Long Way Out"). Use when the user types `/tour`, asks to add/implement the next tour beat, tune a beat's choreography or pacing, or work on anything under docs/tour/. Front-loads the file map, authoring vocabulary pointers, and the add-a-beat checklist so a fresh or post-compaction session starts immediately.

2026-07-147

name	perf
description	Use when measuring, claiming, or investigating anything about render performance — before AND after any renderer/shader/perf change, or when asked "why is this slow?". Runs the headless GPU-timing harness and interprets it correctly.

/perf — measure, don't eyeball

Procedure

Find your dev server's real port. The harness needs a running dev server (/dev skill) and measures whatever that server serves. In a worktree Vite auto-increments past 5173 — read the Local: line of your npm run dev and pass it explicitly:
```
npm run perf -- --url http://localhost:<port> --scenario <name> --frames 30
```
Omitting --url in a worktree silently measures whichever branch owns 5173.
Baseline BEFORE touching code. Run the scenarios covering the regime you're about to change (earth-surface/solar-system for NEAR0 bodies+stars, star-field/milky-way for the star ladder, local-group/full-survey for survey/COSMO). Save the output to a scratchpad file — you cannot reconstruct the "before" after editing.
Re-run AFTER, same flags. Compare MERGED medians. Run-to-run noise is ~0.5 ms at 30 frames — deltas inside that are not a result; raise --frames for finer claims.
Classify before optimizing. --sweep fits time-vs-pixel-count per pass: exponent ≈1 → fragment/fill-bound (resolution levers help), ≈0 → vertex/CPU-bound (they won't). For data-scale costs use --tier large or --compare-tiers.

Interpretation rules (these get misquoted)

Quote MERGED numbers. That's the production encode shape; TOTAL (merged) + its fps ceiling is the headline (GPU passes only — excludes CPU/present/vsync).
Never quote PER-LAYER rows as real costs. Each carries a fixed ~1–3 ms per-pass overhead (full-viewport DRAM round-trip under the instrumented strategy). Use the EST. PER-PASS FLOOR section's floor-subtracted "real" values for attribution. (orbit-trails/body-glints once read 3–4 ms per-layer; they're ~1 ms real.)
Machine parsing: npm run -s perf -- --json — the -s is required or npm's banner pollutes stdout.
CRITICAL on Apple Silicon: MERGED slot-sums are ~3× inflated. TBDR executes passes concurrently, so back-to-back small passes each report the shared retire interval. The tell: adjacent slots with IDENTICAL medians (e.g. hdr→swap / swap·COSMO / swap·NEAR0 all reading 3.2–3.3 ms). Per-slot ms are ordinal at best: never additive, never fps-convertible. The honest total is a wall-clock/rAF probe: boot ?perf, setStrategy('merged'), setPose to the harness pose, collect 240 rAF deltas, then collectTimings and compare. Sustained 120 fps bounds real per-frame GPU work at ≤ 8.3 ms, whatever the slot sums claim.

Off-harness techniques

Paired-baseline A/B. For before/after claims that survive thermal drift: check out the base commit in a scratch worktree (git worktree add --detach <scratch> <base>), symlink node_modules and public/data into it, start a second dev server (Vite auto-increments the port), and alternate runs A-B-A-B across the two URLs instead of measuring all-A then all-B. Remove the scratch worktree after use.
CPU-side frame costs. Bench against the REAL .bin with a tsx scratchpad script that drives the actual code path (name it .mts: the scratchpad has no package.json, so a plain .ts/.js script runs as CJS). "GC churn" diagnoses are usually inline allocation + cache pressure in disguise; measure before optimizing.

Gotchas

Boot timeout + 504 Outdated Optimize Dep in the page errors → the long-running Vite server went stale under a branch switch or new imports. Restart the dev server, re-run.
After editing shaders/renderers, confirm the server picked the change up (HMR line in its output, or restart) before trusting an "after" run.
Scenario poses live in tools/perf/perfScenarios.ts (captured via the in-app l key). Don't drift them — cross-commit comparability is the harness's whole value.