JavaScript engineering

Use this skill for JavaScript implementation, refactoring, debugging, and code review. Optimize for code that is clear, idiomatic, observable, and easy to change—not for maximum ceremony.

Operating procedure

1. Inspect the repository and the nearest code that solves the same problem.
2. Choose the existing convention; if none exists, apply the defaults in this skill consistently.
3. Implement the smallest complete change. Do not broaden the task with cleanup, package migrations, or speculative abstractions.
4. Verify behavior at runtime as well as with tests, linting, or typechecking when those checks exist.
5. Before finishing, review the change against the red flags below and report the checks that ran.

Agent reliability contract

• Inspect before proposing: read the relevant files, package scripts, installed versions, and nearby tests before choosing an API or pattern.
• Keep the patch scoped. Do not rewrite unrelated code, upgrade dependencies, change configuration, or add abstractions unless the requested behavior requires it.
• Never invent an API, package export, framework option, or command from memory. Verify it against the installed package, repository source, or current official documentation.
• Tests must assert the requested behavior and meaningful failure cases. Do not add tests that only assert a mock was called, return a constant, or duplicate the implementation's internals.
• Do not declare success from a clean lint or typecheck alone when the change affects loading, serialization, I/O, browser behavior, or generated output. Run the narrowest real check available.
• Do not hide a failing check with a fallback, broad catch, lint disable, or unrelated config change. Preserve the failure until its cause is understood or report the concrete blocker.

First inspect the project

• Read package.json, the relevant source files, and the existing test, lint, format, and build scripts before choosing patterns.
• Identify the runtime (browser, Node.js, worker, or framework), package manager, module system, supported language target, and established conventions.
• Preserve local conventions unless the user asks for a migration. Do not introduce a new framework, validator, formatter, or abstraction just because it is popular.

Project conventions and engineering style

• Before editing, look for applicable AGENTS.md, CONTRIBUTING.md, STYLEGUIDE.md, README.md, .editorconfig, formatter/linter configs, package scripts, templates, examples, and nearby tests. Check parent and nested directories when the repository is a monorepo.
• Extract the conventions that affect the change: naming, file placement, imports/exports, module boundaries, async and error handling, state ownership, logging, tests/mocks, comments, documentation, and public API shape.
• Follow explicit scoped project instructions and configured tools, then the nearest maintained implementation. Treat a one-off inconsistency as weaker evidence than repeated patterns; if sources genuinely conflict, preserve the narrowest existing contract and report the ambiguity.
• Use the repository's formatter and lint commands for changed files. Do not reformat or rename unrelated code merely to make the repository look uniform.

Consistency protocol

JavaScript has many valid spellings. Reduce unnecessary variation with this order of precedence:

1. Match the nearest working code that solves the same problem.
2. Match the repository's configured tooling and runtime constraints.
3. If the repository is silent, use the defaults below and use them consistently throughout the change.
4. Do not refactor unrelated code just to make the whole repository stylistically uniform.

When several approaches remain reasonable, choose one instead of presenting a menu of equivalent implementations. Mention an alternative only when it changes behavior, compatibility, performance, or maintenance cost.

When the repository is silent, prefer:

• async/await for promise-based control flow; Promise.all with map for independent async work; for...of for intentionally sequential async work. Never use forEach(async () => ...) when the caller must wait.
• One module system per package. Follow existing default-versus-named export conventions; if none exist, prefer named exports for modules with multiple public values.
• find, some, and every for their named intent; map for one-to-one transformation; filter for selection; a loop when early exit, await, or complex control flow is clearer.
• ?? when only null/undefined mean “missing”; || only when every falsy value should use the fallback.
• Shallow object spread for an intentional shallow copy; direct mutation for short-lived, locally owned state. Do not deep-clone by reflex.
• Error objects with useful messages and causes, rather than strings or ad hoc result shapes, unless the project already uses a Result-style API.

Ecosystem pain-point guardrails

These are common sources of wasted time and “almost correct” agent output:

• Architecture and state: trace ownership and data flow before adding a store, singleton, event bus, cache, or utility layer. Keep state close to its consumer when possible, and do not introduce global mutable state to avoid passing a few values.
• Dependencies: search the existing dependency set and platform APIs before adding a package. Add a dependency only when it solves a meaningful problem the current stack cannot solve simply; update manifests and lockfiles with the project's package manager.
• Dates and time: make timezone, locale, precision, and serialization explicit. Do not rely on ambiguous external date parsing or silently treat a local time as UTC. Follow the project's date library or supported platform API.
• Build/runtime behavior: verify the actual entrypoint, package type, extensions, import specifiers, exports, bundler transforms, and test runtime. Code that parses or lints successfully is not necessarily runnable code.
• Debugging: reproduce the failure, form a narrow hypothesis, inspect the relevant source/config/generated output, and make the smallest fix that explains the behavior. Do not change several unrelated variables and call the first green run proof.
• Performance: measure before micro-optimizing, but catch obvious accidental costs such as unbounded concurrency, repeated expensive work in loops, accidental quadratic scans, N+1 I/O, and unbounded caches.
• Package and API boundaries: inspect workspace scripts, package manager, exports, module type, generated artifacts, and the actual consumer/runtime before changing a package boundary. Identify public exports and serialization contracts before making a potentially breaking change.
• Agent drift: do not copy a remembered framework recipe over the installed version. Do not add eslint-disable, // @ts-ignore, broad fallbacks, or a new package just to make a task appear complete; explain and verify the underlying issue instead.

Security at runtime boundaries

Keep security controls where data crosses a trust boundary, using the framework and libraries already established by the project:

• Do not concatenate untrusted values into SQL, shell commands, HTML, templates, filesystem paths, dynamic code, or redirects. Use parameterized/structured APIs, safe sinks, output encoding, sanitization, or allowlists appropriate to the context.
• Treat parsed JSON, deserialized data, request parameters, uploaded files, environment values, and third-party responses as untrusted until the boundary contract is established. Never use eval or an unsafe deserialization shortcut to avoid parsing.
• For user-controlled outbound URLs, enforce the application's intended schemes, hosts, ports, redirect behavior, and network policy where SSRF or open-redirect risk is real.
• Preserve authentication, authorization, CSRF, rate/resource limits, secret handling, and dependency security controls already required by the application. Do not replace them with generic checks or type assumptions.
• Keep secrets, tokens, passwords, and unnecessary sensitive data out of logs, thrown errors, and client responses. Follow the project's redaction and privacy conventions.

Apply the smallest control that addresses the actual threat. Do not add speculative sanitization or validation that changes valid data or duplicates a trusted boundary.

Core coding guidance

• Prefer modern language features that the configured target supports: const by default, let when reassignment is real, modules, destructuring when it improves readability, and async/await for promise-based flows.
• Keep functions and modules cohesive. Prefer simple data flow and named helpers over clever chains, premature generalization, or large “utility” layers.
• Use strict equality and intentional coercion. Treat truthiness carefully when 0, '', false, or null have different meanings.
• Preserve the project's mutability model. Do not ban mutation universally; isolate it when shared state or reasoning complexity makes that useful.
• Avoid eval, string-built code execution, accidental global state, and APIs that obscure ownership or cleanup.
• Match the project's formatting and linting configuration. Formatting preferences are not a reason to make unrelated code changes.

Async and errors

• await independent operations concurrently with Promise.all, Promise.allSettled, Promise.any, or Promise.race according to the required failure semantics. Do not serialize independent work accidentally.
• Handle a promise at the point where its result or failure matters. Do not leave a promise floating unless the fire-and-forget behavior is deliberate and its rejection path is accounted for.
• Catch errors only when you can recover, add useful context, translate to a domain error, or perform required cleanup. Do not catch merely to rethrow, log and rethrow at every layer, or replace a useful error with a generic one.
• Preserve error causes when wrapping (new Error(message, { cause: error }) where the runtime supports it) and keep user-facing/logging decisions at an appropriate boundary.
• Do not add try/catch around every await. Let errors propagate to the nearest layer that can make a meaningful decision.
• For collections whose size comes from users, files, queues, or external services, do not use unbounded Promise.all by reflex. Use the project's existing limiter, batching, or incremental processing when concurrency, memory, rate limits, or cancellation require it.
• Make resource cleanup explicit with the project's supported mechanism (finally, disposers, abort signals, or framework lifecycle hooks).
• When an operation owns timers, listeners, subscriptions, streams, sockets, or clients, define its cleanup and cancellation path. Reuse an existing AbortSignal or lifecycle convention instead of inventing a one-off abstraction.

Validation and defensive programming

Use the smallest amount of validation that protects a real boundary or contract:

• Validate and normalize data crossing a trust boundary: HTTP requests, CLI arguments, environment variables, files, JSON, databases, browser storage, webhooks, and third-party APIs. Check both shape and business meaning when the operation depends on them.
• Once data has been validated, keep the validated representation and do not re-check the same invariant in every helper.
• For internal functions with a clear contract, do not add defensive branches for hypothetical misuse when the caller and control flow already establish the invariant. Fix the caller or type/contract instead.
• Do not use optional chaining, nullish fallbacks, default values, or if (!value) guards by reflex. Add them only when absence is a valid runtime state with intentional behavior.
• Do not add runtime type checks to compensate for a static TypeScript guarantee in code that is actually compiled and controlled by the same project. JavaScript and external data still need runtime checks where the boundary is real.
• Never weaken security or correctness in the name of minimalism. Authentication, authorization, injection prevention, output encoding, resource limits, and input validation remain necessary when the threat or contract requires them.

Testing and verification

• Follow the existing test runner and test style. Test observable behavior, important error semantics, boundary parsing, and regressions; avoid tests coupled to incidental implementation details.
• Prefer small deterministic tests and real collaborators when practical. Mock only unstable, expensive, unavailable, or externally owned dependencies.
• After changes, run the narrowest relevant tests first, then the repository's type/build/lint checks when available. Report checks that could not be run and why.

Observability and logging

• Follow the project's existing logger, structured fields, tracing, metrics, severity, and correlation/request-ID conventions. Do not introduce a second logging system for one feature.
• Record useful context at the layer that owns the operation or can act on the failure. Preserve error causes and avoid logging the same error at every layer.
• Include the event, outcome, relevant operation/resource identifiers, and timing or status data when the project uses them. Never log secrets, access tokens, passwords, or raw sensitive payloads.
• Add instrumentation when it supports debugging, operations, security, or a stated product requirement—not as boilerplate on every function. Ensure logging failures do not turn a recoverable application failure into a new outage unless the contract requires fail-closed behavior.

Review checklist

When reviewing JavaScript, prioritize:

1. Incorrect async sequencing, ignored rejections, races, unbounded work, and cleanup failures.
2. Trust-boundary mistakes, injection/encoding issues, authorization gaps, and unsafe evaluation.
3. Incorrect assumptions about undefined, null, falsy values, mutation, or module loading.
4. Error handling that loses context or silently changes failure into success.
5. Unnecessary guards, duplicate parsing, speculative abstractions, and unrelated churn.
6. forEach(async ...), un-awaited map(async ...), accidental sequential awaits, promise-wrapping of promise APIs, and ||/?? mistakes.
7. Inconsistent module/export choices, hidden mutation, filter(...)[0] where find expresses intent, and optional chaining that masks a broken invariant.
8. Ambiguous dates, dependency churn, global state added without ownership justification, unbounded concurrency, and changes verified only by linting or typechecking.
9. Invented or stale APIs, accidental public-contract breaks, tests with weak assertions or excessive mocks, unrelated file churn, suppressed diagnostics, and completion claims without evidence.

Do not request a stylistic rewrite when the code is correct, readable, and consistent with the repository.

Reference material

Read references/decision-rules.md when you need concrete before/after examples for the highest-impact rules.

Use these as grounding, not as a mandatory one-size-fits-all style guide:

• MDN JavaScript Guide: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide
• MDN modules: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
• MDN promises and async error handling: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises
• Node.js packages and module systems: https://nodejs.org/api/packages.html and https://nodejs.org/api/esm.html
• Node.js test runner: https://nodejs.org/api/test.html
• ESLint configuration: https://eslint.org/docs/latest/use/configure/
• StandardJS rules: https://github.com/standard/standard/blob/master/RULES.md
• Airbnb JavaScript Style Guide: https://github.com/airbnb/javascript
• OWASP input validation guidance: https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html
• OWASP XSS prevention: https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html
• OWASP injection prevention: https://cheatsheetseries.owasp.org/cheatsheets/Injection_Prevention_Cheat_Sheet.html
• OWASP SSRF prevention: https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html
• OWASP logging guidance: https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html
• State of JavaScript 2025 pain points: https://2025.stateofjs.com/en-US/usage/
• 2025 Stack Overflow AI/developer workflow findings: https://survey.stackoverflow.co/2025/ai

The style guides are useful evidence about common practice, not authority over a repository's existing design or the user's stated preferences.