andymai

This skill should be used when adding or extending a geometric shape operation in brepjs — the end-to-end recipe once the target module is chosen (which is decided by architecture-navigation) — when a task says "add a new operation", "add a fillet/draft/shell variant", "expose this Fns function in the public API", "add a method to the shape() fluent wrapper", "new function is missing from function-lookup.md", "knip flags my new export", or "where do I export this from". Covers the *Fns.ts implementation template, the six export surfaces, the function-lookup CI gate, and what to test.

This skill should be used when deciding which layer or module a new file, function, or directory belongs in, or when a layer-boundary check fails. It owns the placement decision (which layer/module) and the import-direction rules — not the end-to-end recipe for wiring an operation through the API ladder (that is adding-operations). Trigger phrases include "where should this file/function go", "which layer is X in", "can topology import from sketching", "layer boundary violation", "check:boundaries failed", "VIOLATION: src/... imports from", "Direct .oc access is banned", "method calls on .wrapped are banned", or adding a new src/ directory or module.

This skill should be used when working on brepjs assemblies, constraint solving, or kinematics — debugging a solve that returns ASSEMBLY_NOT_CONVERGED / ASSEMBLY_MATE_INVALID / ASSEMBLY_SOLVE_FAILED, adding or extending a mate or solver entity-pair, adding a joint type, or driving a mechanism. Trigger phrases include "assembly won't converge", "Unsupported constraint types", "solveAssembly returns Err", "add a mate/joint/constraint type", "extend TRANSLATIONAL_PAIRS", "solveMate: unsupported entity pair escaped filter", "revolute/prismatic/cylindrical/planar/spherical joint", "forwardKinematics", "inverse kinematics / IK target", "DH table / Denavit-Hartenberg", "export/import URDF", or "positioned STEP export from an assembly". Not for boolean fuse/cut compounds (that is debugging-geometry).

This skill should be used when a brepjs GitHub Actions job is red or behaving oddly on github.com (a remote CI run, not a local pre-commit/pre-push hook) — "CI failed", "ci-pass is failing", "npm ci failed with EUSAGE/ETARGET in CI", "test shard timed out", "function-lookup.md diff failed in the build job", "check:patterns fails in CI on code I didn't touch", "npm publish workflow failed", "docs deploy didn't run", "playground smoke is red", "OSV scan is red", "release PR won't auto-merge", or npm ci fails in a CI run after a Dependabot bump on a workspace "*" dependency. Maps each CI job's known failure modes to causes and fixes. For a hook blocking a local commit, use quality-gates or git-pr-workflow instead.

This skill should be used when orienting in the brepjs monorepo's packages/ and apps/ directories — answering "what is brepjs-viewer / brepjs-cad / brepjs-voxel", "is package X published", "which workspace do I edit", "why does npm ci fail with ETARGET on a workspace version-range", "playground shows stale behavior from brepjs-bim/sheetmetal", "in what order do I build the packages", "Dependabot flags a workspace `*` dependency", "add a new workspace package", or deciding how a change in one package ripples into its consumers.

This skill should be used when debugging a geometry failure in brepjs — when a task says "boolean returned an invalid shape", "fuse/cut/intersect returned Err", "the result is empty", "measureVolume returns 0", "autoHeal didn't fix it", "shape is invalid", "STEP export crashed" or "WebAssembly.RuntimeError during export", "the part looks wrong, render it", "works on occt-wasm but fails on brepkit", or "is this a kernel divergence". Covers triage, numeric sanity checks, the healing pipeline, boolean failure modes (including the

This skill should be used when committing, pushing, branching, or merging in the brepjs repository — when a task involves "pre-commit hook failed" (which tier ran, how to bypass), "commit rejected by commitlint", "subject may not be empty", the pre-push knip tier firing, "create a branch", "set up a worktree", "open a PR", "arm auto-merge", or deciding whether a commit needs a `!` breaking marker. Covers hook anatomy and tiers, conventional-commit message format, branching, worktrees, and the PR/merge process. For diagnosing a specific gate or lint error see quality-gates; for a red CI job see ci-triage.

This skill should be used when working on the brepjs kernel abstraction layer or across multiple kernels — adding a kernel method, wiring or writing an adapter, switching or registering kernels, or reasoning about kernel capability differences. Trigger phrases include "add a kernel method", "new kernel method", "withKernel", "brepjs kernel not initialized", "kernel 'X' is not registered", "is only available with the brepkit kernel", "occt-wasm: ... is not yet implemented", "run this under manifold/brepkit/occt", "which kernel supports X", "kernel capabilities", "quality tier", "regenerate the conformance matrix", or working on adapter/interface/registry/capability design under src/kernel/. Raw Emscripten/heap mechanics belong to the wasm-interop skill.

Use at the start of an autonomous or unsupervised session to pick what to work on, when deciding whether a geometry case is worth chasing, when a task looks like something a past session already tried, or before claiming a case is closed. The sanctioned work-selection doctrine: what is open and ready, what is terminal, the chase filters, and the acceptance bar.

Use when adding or changing methods on BrepKernel in crates/wasm, wiring ops into executeBatch, writing tests for bindings, building the wasm package (wasm-pack or cargo xtask wasm-build), testing a local kernel build inside brepjs or another JS consumer, or debugging wasm-only failures such as tests that will not compile with JsError, panics that abort the wasm instance, "recursive use of an object" errors, or a JS app silently loading a stale wasm build. Also use when the CI "WASM Binary Size" PR comment shows growth or a change adds a dependency to the wasm graph.

Use when adding a new modeling operation to crates/operations (a new pub fn taking &mut Topology and returning a SolidId or similar), when extending an existing operation with a new code path, or when an operation's tests need to prove correctness before shipping. Covers implementation traps, error handling, test placement, wasm exposure, and the verification bar.

Use when a boolean, revolve, offset, or other operation degrades exact analytic geometry (planes, cylinders, cones, spheres, tori, circles) to NURBS or a mesh fallback, when face counts explode from a handful to hundreds, when running or interpreting the approx_census, when adding an exact analytic-analytic intersection arm, or when deciding whether an analytic-recovery task is worth chasing at all.

Diagnose and fix failures of the GFA boolean engine (fuse, cut, intersect). Use when a boolean result mesh-falls-back to hundreds of all-planar faces, comes out non-manifold or open-shelled, is missing faces, has wrong volume, fails the Euler or validation gates, errors in shell assembly, or gives different results across runs.

The meta-method for debugging hard geometry bugs in brepkit, used when a boolean, fillet, offset, or tessellation produces wrong volume, wrong face count, open or non-manifold shells, mesh fallback, misclassified points, or any failure where the first diagnosis did not immediately hold. Also applies before starting any multi-pass investigation, when a repro behaves differently from the real case, or when successive root-cause theories keep overturning each other.

Diagnose fillet and chamfer bugs by locating which engine owns them, debug the v2 walking blend, and avoid the silent no-op success in the public fillet binding. Use when a fillet or chamfer leaves free edges, produces an open or non-manifold shell, silently changes nothing, degrades a cylindrical wall to NURBS, or when deciding whether to touch the deprecated v1 fillet code.

Use when a STEP or other file imports wrong (missing solids, all-NURBS where analytic was expected, hard UnsupportedEntity errors), when verifying writer output round-trips, when capturing a faithful fixture from a real file, or when adding or extending a format in crates/io. Covers the format matrix, STEP reader anatomy, the analytic round-trip check, and heal-after-import.

BREP generation pipeline in src/features/generation — adding/changing bin features (cutouts, handles, patterns, text), wall-pattern border clipping, overhang/inner dims, shapeCache keys, dual-kernel draft-vs-export parity, generation.worker.ts / WASM kernel lifecycle, brepjs bumps. Symptoms — jagged wall edges, stale preview after param edit, draft missing a feature, non-manifold export, "Cannot pass deleted object", timeouts after generator changes.

Zustand stores (src/core/store/) and the CQRS v2 pipeline (src/core/cqrs/) — adding a command/event end-to-end with defineCommand and its hand-maintained registries, undo capture and batch(), event versioning/migrations, persistence (localStorage/IndexedDB/useAutoSave), the init-time-literal store rule (#1466), useShallow. Symptoms: "No handler registered for command type", undo toast shows generic "Undid: Action", Ctrl+Z not reverting, "Maximum update depth exceeded", "Missing migration".

Write and run tests — Vitest three-project routing (unit/dom/generators), src/test/ utilities (resetAllStores, createTestLayout, expectOk), real-WASM geometry scenario tests and triangleCount snapshot updates, __kernel-tests__ profile config, Playwright e2e/smoke/visual, benchmarks. Load for "document is not defined", "Cannot pass deleted object", tests passing alone but failing in the full run, flaky e2e, coverage-threshold failures, or updating scenario snapshots.

PostHog event conventions (trackEvent, snake_case names, #1466 import-cycle rule), ML telemetry pipeline (/api/ml-telemetry, label hashing), labs feature flags (FEATURE_FLAGS, useFeatureFlag, graduate/remove), and shared-hook traps (stale closures, cross-tab sync, auto-save races). Load when adding/renaming analytics events, adding or removing a labs flag, debugging "event never appears", "flag toggle does nothing", or "blank page in production build".

OAuth sign-in (api/auth/: login, callback, me, logout, Arctic providers) and per-user cloud sync (api/sync/: layouts, designs, manifest, export, account; src/core/sync/ engine). Use when debugging sync 401/403/409/410/413, forced sign-out, LWW conflicts, tombstone resurrection, manifest 304/If-Modified-Since staleness, index↔blob drift (pnpm sync-admin), GOOGLE_/GITHUB_CLIENT_ID / OAUTH_REDIRECT_BASE_URL env, or the __Host-gflt_session cookie.

Custom bin editor (src/features/bin-designer/) — compartment grid model and the normalizeIdsWithRemap parallel-array rule, epoch-based worker regeneration via pushHistoryEntry, label tabs/compartmentTexts, wall cutouts/handles, and the client/server validation mirror in api/lib/designerValidation.ts. Load when adding a BinParams field, editing merge/split/setCompartmentGrid, labels land on the wrong compartment, cloud sync returns 400 INVALID_PARAMS, or the 3D preview stops updating.

SEO/content pages: adding a landing page end-to-end (content/*.md → scripts/build-content.ts → public/<slug>/index.html), the "⚠ ... chars" SERP title/description warnings, sitemap.xml + hreflang, regenerating OG cards and screenshots (pnpm run gen:seo-images, gen:example-thumbnails), /designer + /baseplate static heads (scripts/build-route-entries.ts), editing index.html meta/JSON-LD, and the phone-scan handoff endpoint api/scan-session.ts ("scan" PR scope).

Cross-cutting debugging method for any bug report or regression — git archaeology on fix commits, reproduce-first, fixing every layer — plus an index of the trap classes that recur in git history. Load when a symptom has no obvious owning subsystem, when a fix "works" but you cannot explain why, or for symptoms like silent bounding-box fallbacks, preview-vs-export divergence, half-grid crashes, wedged workers, "undefined (reading dispatch)", or a slicer rejecting a 3MF.

Protect Unity project integrity when touching assets — keep .meta/GUID pairing intact, never hand-edit scene/prefab YAML or binary assets, route hierarchy/prefab changes through the Editor, and keep .gitignore/LFS/merge config correct. Use before moving, renaming, or deleting Unity assets, or when editing .meta, .unity, .prefab, or .asset files.

Run headless Unity builds and CI — batchmode player builds, Addressables content builds, and test/build pipelines (GameCI). Invoke deliberately with /unity-build; this never auto-runs because builds are long and side-effecting.

Write idiomatic, performance-safe Unity 6 C# — MonoBehaviour lifecycle, ScriptableObject + event-channel architecture, serialization, the Input System, and assembly definitions. Use when writing or editing Unity C# scripts (.cs), adding gameplay systems, components, or ScriptableObjects, or wiring data and events in a Unity project.

Drive the live Unity Editor as a feedback loop — recompile after edits, read the console for compile errors and runtime exceptions, capture the Game/Scene view to verify visually, and debug runtime issues. Use after editing Unity scripts, when the game misbehaves or throws, or when you need to see what the Editor is actually rendering.

Diagnose and fix Unity performance problems with a profiler-guided workflow — eliminate GC allocations and per-frame spikes, pool objects, batch work, and measure before and after. Use when a Unity game is slow, stuttering, dropping frames, or showing GC spikes, or when asked to optimize Unity runtime performance.

Write and run Unity Test Framework tests — EditMode (fast, logic) and PlayMode (scene/lifecycle) — via headless batchmode, parse the NUnit XML results, and pair them with visual capture so "tests pass" actually means "the game works". Use when adding or running Unity tests, setting up test assemblies, or verifying gameplay behavior.

Build Unity UI with UI Toolkit — UXML structure, USS styling, data binding, and the runtime vs Editor UI split. Use when creating or editing .uxml or .uss files, building runtime HUDs/menus or custom Editor windows/inspectors with UI Toolkit (not uGUI).