engineering-standards · git:20260831.d813a96 · 2026-08-31 · sha256 df5d679f885bc34e
engineering-standards git:20260831.d813a96A
Immutable. This exact content never changes and is served at /api/v1/blob/df5d679f885bc34e.
--- description: Core engineering standards for this foundational UI library alwaysApply: true --- # Engineering Standards This is a foundational library laying groundwork for the future. "Good enough" is never acceptable. ## Approach - **Never take shortcuts.** If a plan calls for a fundamentally different architecture, implement it differently — don't rename the existing one and call it new. - **Flag deviations immediately.** If you can't implement what was asked, say so and explain what you don't understand. Never silently substitute an easier alternative. - **Understand before implementing.** If a design or proposal isn't fully clear, ask questions first. Don't start coding until the model is understood. - **Correctness over speed.** Take the time to get it right. A wrong implementation that passes tests is worse than no implementation. ## When Comparing Approaches - Each approach must be architecturally distinct, not a rename of the other. - Identify the specific structural differences before writing code. - If two approaches converge to the same implementation, stop and report that — it's a finding, not a failure. ## Changesets **CRITICAL — NEVER SKIP THIS STEP.** Every commit that changes source files under `packages/` MUST include a changeset. This is a hard requirement, not a suggestion. **Before running `git commit`**, always: 1. Check if the staged changes touch any files under `packages/*/src/` — if yes, a changeset is required. 2. Create the changeset file (`.changeset/<descriptive-name>.md`). 3. Stage it alongside the code changes. 4. Only then run `git commit`. Since `pnpm changeset` is interactive and cannot be used from the agent, create the file directly: ```markdown // .changeset/<descriptive-name>.md --- "@solidjs/signals": patch --- Short summary of the change ``` - **While in prerelease mode (versions like `2.0.0-rc.x`), every changeset is `patch`** — no exceptions, features and breaking changes included. The usual semver mapping (`patch` fixes / `minor` features / `major` breaking) applies only to stable releases. - List the package(s) that actually changed, by directory. Source under `packages/solid/src/` → `solid-js`; `packages/signals/src/` → `@solidjs/signals`; `packages/web/src/` → `@solidjs/web`; etc. If a single change touches multiple package sources, list each one. (All packages in the `fixed` group still version together; the changeset header is documenting *what* changed, not *what bumps*.) - If a commit only touches examples, tests, or tooling config (not source under `packages/`), no changeset is needed. - The changeset file name should be descriptive (e.g., `fix-ssr-async-error-handling.md`), not random words. ## Communication - Be direct about what you don't know or don't understand. - Never let the user discover a mistake you could have caught — if something seems off, raise it proactively. - When debugging, reproduce the issue in a test before attempting fixes. Don't spin in circles with speculative changes.