Development

Feature / Bug-Fix Development Checklist

This skill is a checklist of guardrails for feature and bug-fix work — reminders to catch missing work during development, then hand off to the more specific workflow when needed. The sections roughly follow a task's lifecycle for easy reading, but treat them as prompts to apply where relevant, not a rigid pipeline.

Confirm Intent & Scope

Decide what the task actually is before doing any work.

• If the request is phrased as "review / verify / assess", treat it as investigation — report findings and confirm before implementing anything.
• When the user enumerates a subset ("only the low items", "core field only", "先只加 skip"), implement exactly that subset and stop.
• If a fix would span multiple clusters or packages, estimate file/PR size and confirm scope before writing code. Keep one PR per coherent seam.

Build Verified Context

Gather the real inputs and ground every claim in something you read this session — never answer from memory or impression.

• For GitHub issues/PRs/checks/reviews, read the linked context before editing; do not implement from the title alone.
• For external repros, reproduce with the smallest command first (workflow: testing → External repro projects).
• Identify the smallest user-visible behavior, the affected package(s), and the validation path.
• Behavioral, root-cause, version, or package-name claims must cite path:line — never answer from recall.
• To answer "how does vitest/jest/rsbuild/rspack behave?", read the latest upstream source, not the built node_modules dist: if a local clone exists (e.g. ~/Projects/vitest), bring it up to the latest default branch before reading (git pull — a git fetch alone leaves the working tree stale); otherwise shallow-clone fresh (vitest → vitest-dev/vitest; rsbuild/rspack → web-infra-dev/{rsbuild,rspack}; npm view <pkg> repository finds others). Prefer a subagent for the lookup.
• If you cannot verify, say so explicitly instead of guessing.

Map the Blast Radius

Before writing code, determine what the change reaches:

Public API / Config / CLI Checklist

For public API/config/CLI changes, check the full surface in one pass:

1. Canonical type/default/normalization/runtime consumer.
2. CLI flag/help/output/error text when applicable.
3. Adapters (rsbuild, rslib, rspack), browser mode, and docs (en, zh, ApiMeta) impact.
4. Unit tests for internals/transforms; e2e tests for user-facing behavior.

Implement the Minimal Root-Cause Fix

Make the smallest design change that resolves the root cause — this is where design-scope decisions belong. For in-file code quality (any/as, defensive checks, one-use abstractions, single source of truth, catch-and-rethrow), defer to the typescript skill rather than restating its rules here.

• Fix at the single origin of the bug with the fewest lines. Find the one source, not N symptoms.
• Do not add new config knobs, buffers, heuristics, timeouts, dependencies, abstractions, or mode-specific hacks (e.g. string-replacing the Rspack runtime) unless the user asks. Surface any such need as an explicit decision point or follow-up issue — never take the shortcut silently.
• Before adding a top-level config option, prove the existing channel (inlineConfig / run params) cannot express it.
• When aligning behavior with another tool, match the reference impl as the parity target — read its source (the latest upstream clone, per Build Verified Context), not the node_modules dist. Don't harden edges beyond it.

Prove It Empirically

Every behavioral change — feature or bug fix — must have a corresponding e2e test. Unit tests alone are not enough; e2e tests verify the full CLI → runner → reporter pipeline.

Decide whether test work is required here. For test layout, fixture strategy, rebuild requirements, and exact commands, switch to the testing skill. For what counts as evidence that the change works — forbidden proxy signals, per-change-shape observation standards — defer to the verify skill rather than restating its rules here.

When Test Work Is Required

• New feature or config behavior → add or extend an e2e test that exercises the user-facing flow.
• Bug fix → add a regression test that fails before the fix and passes after it.
• Internal refactor with no observable behavior change → evaluate whether existing coverage is enough, and note why if no new test is added.

Bug-Fix Tests (Flip-and-Verify)

Prove the repro both ways before claiming a fix:

1. Run the repro against origin/main (unfixed) → confirm it fails.
2. Run the same repro with your fix applied → confirm it passes.
3. Add the regression test that captures this delta.

Never present a hypothesis as a conclusion — state confidence explicitly; "I believe" is not "verified".

Browser Mode Impact

Not every feature needs browser mode support, but you must consciously decide rather than ignore it.

When Browser Mode Needs Changes

• The feature touches test execution, module resolution, or runtime APIs → likely affects browser mode.
• The feature adds a new config option → check if it should apply in browser mode too.
• The feature modifies the reporter, CLI output, or test filtering → usually Node-only, but verify.

When Browser Mode Does NOT Need Changes

• Pure Node-specific features (e.g., process.env handling, Node module mocking).
• Internal refactors that don't change the runtime contract.