Ejecuta cualquier Skill en Manus
con un clic

Ejecuta cualquier Skill en Manus con un clic

perf

Estrellas7

Forks1

Actualizado22 de julio de 2026 a las 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.

Instalación

Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.

Ejecutar en Manus

Fuente

rulkens

rulkens/skymap

Abrir repositorio de GitHub Ver repositorios del creador

Descarga

Ejecutar en Manus

Ocupaciones relacionadasSOC

Basado en la clasificación ocupacional SOC

Desarrolladores de softwareOcupaciones informáticas y matemáticas·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.

Más de este repositorio

mismo repositorio

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

/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.