validate

Validation

• Browser FIRST. Before running any CLI validation, verify your changes work in the browser via Playwright. Navigate to affected pages, confirm the feature works, take screenshots. Broken code that passes lint is still broken. Browser is the source of truth. Exception: the per-file story loop in frontend:validate-file reproduces with pnpm test:story first and checks the browser once the story test passes
• Browser verification: see frontend:playwright skill for all rules on screenshots, critical examination, browser_evaluate measurements, and visual debugging. NEVER ask the user to check their browser: that is YOUR job
• FLAKY SUITES NEED MULTIPLE RUNS. Storybook/browser/e2e/msw tests are flaky on a single run. Before declaring green, run 3x in a row from a clean state: kill the test server port, delete node_modules/.vite and node_modules/.cache/storybook, then run. ALL three must pass. One green run is meaningless
• SETUP TIME VARIANCE IS A FLAKE FLAG. If the same suite shows setup time varying by >30% between runs (e.g. 100s vs 200s), the runs are not equivalent: one of them is silently skipping imports. Do not trust either count until you understand why
• MATCH THE USER'S RUN CONDITIONS. When the user reports a failing run, reproduce their EXACT state before claiming a fix worked: same branch, same lockfile, same cache state. If you cannot reproduce their failure, say so out loud: do not paper over it with your own green output from a different cache state
• Test Files N passed (N) ≠ verification. Always cross-check the test count against the expected total. A run that "passes 85/85" test files but only executes 147 of 192 tests has silently skipped 45 tests, about 23% of the suite
• Before declaring done/fixed: run pnpm validate when package.json has it. The SETUP.md template (repo root, not shipped with the plugin) runs test:unit and lint:summary concurrently, then test:storybook; lint:summary covers knip, svelte-check, oxlint, eslint and stylelint, and pnpm validate:build below adds the builds. Must exit 0, and its lint table must show no failure: the template lint-summary.ts exits 0 even when a lint task fails. A CSS-only change: see the exception under pnpm validate:build below
• Run pnpm test:unit (vitest) after every change. pnpm test, where a project defines it, can also launch Playwright e2e tests (with the sv add playwright config, Playwright's webServer builds and previews the app first; in another config, its webServer setting decides whether a server must already run): use pnpm test:unit for quick feedback
• Test in the correct mode: dev changes to pnpm dev, not pnpm build
• Exit code 0 or it's not verified. Crashes ≠ passes
• Crashed baseline ≠ valid baseline. Incomplete runs have meaningless timing
• Timed-out command = failed verification. Task is NOT done
• Single-file success ≠ full-run success. Always run the full command
• Get a baseline BEFORE making config changes, then compare
• Never declare "done" when error counts drop. Compare rule-by-rule
• Unit tests prove nothing about component APIs: verify in browser (see frontend:playwright skill)
• pnpm test:unit exercises msw handlers only where a test sends a request through msw: a browser test that mounts a component that fetches, with the worker started (e.g. in a setup file), or a node test with setupServer listening. Handlers and fixtures that only stories use, and Storybook rendering, need the storybook project and a browser check (svelte-5:msw, svelte-5:storybook-vitest)
• When fixing a bug found via browser interaction: reproduce the exact user flow via Playwright BEFORE declaring done
• Never declare "done" when verification failed or was skipped
• Show proof, not summaries
• VALIDATE AFTER EVERY SINGLE FILE EDIT. Not after a batch. Edit one file, run checks, confirm 0 errors, then move to next file. NEVER batch edits across multiple files without validating between them
• pnpm lint:file <file>: run this on every edited file. It runs eslint + knip, oxlint for JS and TS files, plus svelte-check (with --tsgo by default) when the list holds a .svelte file, or tsgo --noEmit when it holds a TypeScript file (.ts, .tsx, .mts, .cts) and no .svelte file (a list with neither gets no type check), with the type-check and knip output filtered to the listed files. Without tsgo installed, its tsgo step still reports ✓, and so does its svelte-check step unless SVELTE_CHECK_FLAGS drops --tsgo, so install every tool first (SETUP.md; other false-green cases: frontend:validate-file, type-check caveats)
• .svelte, .svelte.ts, .svelte.js files: ALWAYS run the Svelte autofixer (mcp__plugin_svelte_svelte__svelte-autofixer) after editing to validate Svelte 5 correctness, except on a .svelte file not yet migrated (pure Svelte 4: export let, $:, <slot />, no runes; frontend:validate-file story loop, step 5). pnpm lint:file does not run it: the template's lint-file.ts has no autofixer step
• CI workflow changes: simulate the CI environment locally before pushing. Run commands with CI=true GITHUB_ACTIONS=true to catch tools that auto-detect CI and change behavior (e.g. oxlint switches to --format=github). NEVER push a CI "fix" without local CI simulation first
• GitHub Actions workflow files: ALWAYS run pnpx [email protected] <file> after editing any .yml or .yaml workflow file in .github/workflows/. Exit code 0 or it's not valid. Check the path with test -f <file> first: for a path that matches no file, and for a directory, node-actionlint prints nothing and still exits 0
• Use pnpm validate:build as the final verification: runs validation and build tasks concurrently. See SETUP.md for how to configure this script. One command, everything checked. Exception: a CSS-only change needs no build: verify it visually via Playwright, plus lint, vitest and svelte-check
• Run the TEST TYPE you changed. If you modified Playwright tests, run pnpm test:e2e (where the project defines it, as sv add playwright does; otherwise not covered here). If you modified vitest tests, run pnpm test:unit. If you modified stories, run pnpm test:storybook. The SETUP.md template's pnpm validate runs no Playwright e2e. Changed tests must actually execute and pass
• LINT TEST FILES: pnpm lint:tests. One command, runs 4 linters: oxlint and eslint on the test files matching TEST_GLOBS (src/**/*.test.ts and tests/**/*.test.ts by default), knip and svelte-check (with --tsgo by default) on what knip.tests.jsonc and tsconfig.tests.json cover. Lint a *.e2e.ts test from sv add playwright, a *.spec.ts test, or a test file outside the TEST_GLOBS patterns with pnpm lint:file. Without tsgo (with the default --tsgo flag) or without tsconfig.tests.json, its svelte-check step reports ✓; a missing knip.tests.jsonc fails its knip step; when no file matches TEST_GLOBS it lints nothing and exits 0 (SETUP.md). Must exit 0. Do NOT run individual linters: you WILL forget one
• One problem at a time. Fix ONE problem, verify it passes, then move to the next. Never batch unrelated changes: changing two things at once makes it impossible to tell which change broke what
• Capture expensive test output. When running Playwright or e2e tests, pipe to tee /tmp/test-output.log. If output is already in context, READ IT: never rerun. NEVER run the same expensive command twice in a row just to grep differently
• Final checklist before declaring done: Browser verified? Linted? pnpm validate:build exit 0 with no failure in its lint table (or, for a CSS-only change, the exception above)? Each edited workflow file passed test -f and then exited 0 under pnpx [email protected]?
• NEVER trust subagent claims. After EVERY subagent completes, run git diff to see what actually changed. Subagents can claim "done, no changes needed" while having silently modified files, or claim "fixed" while having broken something. Never tell the user "I didn't change that" without checking git first