node-version-discipline
Installation
SKILL.md
Node Version Discipline
Before running any build / lint / type-check / test / install command in a Node project, align the Node version to the project's declared version (probe the full chain:
.nvmrc→.node-version→.tool-versions→volta.node→engines.node→ CI config). Otherwise verification results are untrustworthy.
1. Why alignment is mandatory
The host's default Node version (e.g. v22) frequently mismatches the project's .nvmrc-pinned version (e.g. v14). Running tsc / eslint / npm run build / npm test on the default version produces:
| Risk | Effect |
|---|---|
| False pass | Higher Node is more permissive — tsc/eslint pass, but the pinned version actually crashes at runtime |
| False fail | Higher Node breaks legacy toolchains (e.g. Webpack 4 native deps), surfacing build errors unrelated to the code and misdirecting the investigation |
| Behavioral drift | Older versions lack APIs (structuredClone, AbortController...) — runtime behavior diverges |
| Dependency resolution skew | node_modules installs native modules for whichever Node is active; mismatch installs the wrong variant |
Core lesson: even if a higher version happens to pass and results coincidentally match, the
.nvmrc-pinned version is the source of truth. "It passed on a higher version" never justifies skipping alignment.