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.