engineering-standards · git:20260906.b1b38c3 · 2026-09-06 · sha256 0b5d5047fdf54bcc

engineering-standards git:20260906.b1b38c3A

Immutable. This exact content never changes and is served at /api/v1/blob/0b5d5047fdf54bcc.

---
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.

## Questions are not instructions

When the user's message is a question, an opinion, a reaction, or thinking out loud ("is this right?", "seems complicated", "I wouldn't mind if…", "do you know what that is?"), the deliverable is an answer. Do not edit files, run tests that mutate state, commit, or push in that turn — even if the answer makes the next step obvious. Propose the step and stop.

Act only on an imperative from the user ("do it", "ok", "go", "fix it", "commit"). An "ok" applies to the specific proposal it answers, not to follow-on work discovered afterward.

Commits and pushes always require an explicit ask in the user's latest message. Otherwise stage and report.

## 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.