skymap

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.

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.

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

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.

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.

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.

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.

Use when adding a galaxy to skymap's famous layer — the named Messier/Caldwell/notable galaxies that get a thumbnail quad on close approach and a rich InfoCard. Triggers like "/add-famous", "add a famous galaxy", "add M64 to the famous catalog", "curate a new galaxy thumbnail", or "put NGC 5128 in the famous layer". Also for re-curating an existing famous galaxy's thumbnail.

Symlink the current worktree's `public/data/` to the main checkout's `public/data/`, so the worktree renders against the same real catalog data without rebuilding. Use when the user types `/link-data` or asks to "use real data here", "link the data", "stop falling back to synthetic", or sees `unsupported version: N — please regenerate the .bin via "npm run build-tiers"` warnings in the dev-server log. Idempotent: re-running on an already-linked worktree is a no-op.

Create a fresh git worktree from a short description and drop the session straight into it. Use when the user types `/wt <description>` or asks to "start a worktree for X", "spin up a worktree", "work on X in a worktree", or "branch off into a worktree". Derives a kebab-case name from the description and calls the native EnterWorktree tool (fresh from origin/main).

Use when reviewing a diff, file, or module for simplicity — before or after a refactor, or when concerns feel tangled and you want the complecting named precisely rather than as vibes. Also at DESIGN time, over a spec or plan you're writing, the moment a section exists to teach careful handling of an "asymmetry" / "subtlety" / "special-case" / "must-remember-to". Triggers like "is this complected / too complex", "simplicity review", "/entanglement-radar", a second branch on the same discriminant, a duplicated constant, a renderer mirroring EngineState, or a state field written by one path but read-for-truth by another. Skymap-specific; complements /code-review (correctness) and /simplify (applies fixes).

Use when applying a simplicity fix in skymap — taking a complecting knot named by /entanglement-radar (or one you spot) and actually un-braiding it in the code, keeping the suite green. Triggers like "/simplify", "apply the un-braiding", "decomplect this", "fix the mirror state", "consolidate these branches into a registry", or any follow-through after an entanglement-radar review where the next step is to change the code, not just describe it. Skymap-specific; complements /entanglement-radar (names knots) and /code-review (correctness). Scoped to one coherent un-braiding per run, applied on a branch.

Use when cutting a tagged version release of skymap — triggers like "/release", "cut a release", "tag v0.X.0", "release the new version", "bump and release", or when a new Zenodo DOI needs minting for a version.

Scaffold a new Architecture Decision Record under docs/adrs/ with the project's template, auto-numbered. Use when the user types `/adr` or asks to "create an ADR", "write an ADR for X", or wants to document an architectural decision. Use proactively when the assistant is about to make a non-obvious architectural choice — codify the decision before the code lands so future readers (humans and agents) can reconstruct the why.

Start or stop the skymap Vite dev server in the current worktree. Use when the user types `/dev` or `/dev-stop`, or asks to "start the dev server", "spin up dev", "kill the dev server", or similar. Backgrounds `npm run dev` and reports the URL; reuses the running server if one exists in this session.

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".