VarLens

Use when changing filtering, sorting, searching, column definitions, column metadata, or filter-related UI on the VarLens single-case variant view — or the cohort view — before deciding scope, writing the plan/spec, or opening the PR. Symptoms of about to violate: editing useFilterState.ts / FilterToolbar.vue / VariantTable.vue / variant-table/columns.ts and thinking "I'll add the cohort side later", "cohort is out of scope for this PR", or "the cohort view can catch up separately".

Use when a VarLens test or app run fails to load the native SQLite module — errors like NODE_MODULE_VERSION mismatch, "compiled against a different Node.js version", ERR_MODULE_NOT_FOUND on out/main/db-worker.js, or "was compiled against a different Node.js ABI" — or BEFORE running vitest, the Electron app, or packaging, to rebuild the module for the correct ABI first.

Use when reviewing a VarLens change for security issues or bugs before commit/PR/merge — auditing IPC, Electron window/fuses, database-key, external-URL, or import code — or running a pre-merge scan. Symptoms: adding an IPC channel that takes untrusted input, changing webPreferences/fuses, handling SQLcipher keys, calling shell.openExternal, adding a dependency, or hunting a suspected bug in a diff.

Use when about to claim a VarLens change is done, working, fixed, or ready to commit/PR — to pick and run the right make target for what you changed and report its actual output. Symptoms of about to skip this: "the diff looks clean", "types should pass", "this is a trivial change", "I'll let CI catch it", or claiming a UI change works without opening the app.

Use when adding, renaming, or changing an IPC channel between the VarLens renderer and main process — exposing new data or actions on window.api, wiring a new domain, or touching preload/contract/handler code. Symptoms include "how do I call main from the renderer", editing src/preload or src/main/ipc, a failing tests/shared/types/preload-contract.test.ts, or a renderer call that returns a SerializableError instead of data.

Use when building or changing VarLens renderer UI — Vue 3 + Vuetify 4 components, dialogs, side panels, data tables, colors, backgrounds, hover states, or theme work. Symptoms of about to get it wrong: reaching for surface-variant or a hardcoded hex for a background, a v-data-table-server whose row expansion silently does nothing, adding console.log in a component, or styling that looks fine in light theme but breaks in dark.

Use when extending or debugging VarLens VCF import — mapping a new INFO field to a DB column, changing annotation parsing (VEP CSQ or SnpEff ANN), touching multi-allelic splitting, genotype/sample handling, SV/CNV/STR extension fields, or anything under src/main/import/vcf/. Also use before assuming which column holds the impact level vs the Sequence Ontology term.