validate-change

Validate a Change

Companion Guidance

Use karpathy-guidelines alongside this skill for implementation or review work. Keep changes scoped, surface assumptions, and define focused validation before editing.

Use this skill to choose the smallest validation set that still covers the surfaces touched by a change.

Mandatory Rules

• Format changed files with the language-native formatter before the final lint/test pass.
• If any Rust code changed, always run just test-rust.
• If any Rust code changed, also run cargo fmt --all.
• If any Rust code changed, also run cargo clippy --workspace --all-targets -- -D warnings.
• If crates/core or crates/adaptive changed, run the full matrix across Rust, Python, Go, and Node.js.
• If a language surface changed, always run that language's test target even when Rust core did not change.
• If dynamic plugin behavior changed, use maintain-dynamic-plugins and include the native SDK, worker protocol, Python SDK, docs, packaging, and Codecov surfaces in the validation plan.
• If code changes alter APIs, bindings, commands, paths, packaging behavior, observability/adaptive semantics, or documented best practices, update any dependent maintainer or consumer skills in the same branch.
• During iteration, prefer uv run pre-commit run --files <changed files...>.
• Before review or handoff, run uv run pre-commit run --all-files.

Start With The Change Shape

• Core runtime or shared semantics changed Use test-rust-core. This always includes just test-rust, cargo fmt --all, cargo clippy --workspace --all-targets -- -D warnings, and the full matrix across Rust, Python, Go, and Node.js.
• Python-only wrapper or binding change Use test-python-binding.
• Go binding change Use test-go-binding.
• Node.js binding change Use test-node-binding.
• FFI surface change Use test-ffi-surface.
• Framework integration change Run the relevant language test target and focused integration tests or smoke path.
• Dynamic plugin loader, SDK, or protocol change Use maintain-dynamic-plugins. Run the targeted plugin crates and just test-python-plugin first, then escalate to the core validation matrix when runtime behavior or crates/core changed.
• Docs-only change Run targeted checks only if commands, package names, or examples changed. Use just docs for docs-site builds and just docs-linkcheck when links changed. The ./scripts/build-docs.sh wrapper remains available for compatibility.

Core Validation Matrix

just test-rust
just test-python
just test-go
just test-node

Common Targeted Commands

# Rust only
just build-rust
just test-rust
just ci=true test-rust
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings

# Python
just build-python
just build-python-plugin
just test-python
just test-python-plugin
uv run ruff format python
uv run pytest -k "<pattern>"

# Go
just build-go
just test-go
cd go/nemo_relay && go fmt ./...

# Node
just build-node
just test-node
npm run format --workspace=nemo-relay-node

# Docs site
just docs
just docs-linkcheck

Layer-Specific Skills

• test-rust-core
• test-python-binding
• test-go-binding
• test-node-binding
• test-ffi-surface
• maintain-dynamic-plugins

Pre-commit Semantics

Use pre-commit in two modes:

• During iteration, run uv run pre-commit run --files <changed files...>.
• Before review or handoff, run uv run pre-commit run --all-files.

Important: --files still triggers any matching hook whose files or types selectors match the provided paths. Some hooks then ignore filenames and run a whole-language or workspace-wide command because they are configured with pass_filenames: false.

Examples from this repo:

• Matching Python files run Ruff on the selected files, and also trigger ty check . ... for the Python project.
• Matching Rust files trigger cargo fmt --all --, cargo clippy --workspace --all-targets -- -D warnings, and cargo check --workspace --all-targets.
• Matching Go files trigger gofmt on the selected files and go vet ./....
• Matching docs markdown files under README.md, CONTRIBUTING.md, or docs/ trigger the docs link checker.
• Matching Cargo.toml, Cargo.lock, or deny.toml triggers cargo deny check.
• Matching Cargo.lock, uv.lock, or package-lock.json triggers the attributions generators.
• Matching Node.js public JS/TS surfaces can also trigger the public docstring checks, while matching Node.js JS/TS files trigger the prettier wrapper.

Hygiene Checks

Run these whenever the change is headed for review. Rust changes should still run cargo fmt --all and cargo clippy --workspace --all-targets -- -D warnings even if you also plan to rely on pre-commit.

cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
uv run pre-commit run --all-files

If the change is large or public-facing, also verify:

• README and docs entry points still match current package names and paths
• Examples still run with the documented commands
• Any renamed public surfaces are reflected consistently in manifests and docs
• Dynamic plugin examples exclude Relay versions before 0.8. The recommended range is compat.relay = ">=0.8.0,<1.0"; open-ended or narrower 0.8-or-newer ranges are valid when intentional.

References

• Testing guide: docs/contribute/testing-and-docs.mdx
• Contributor guide: CONTRIBUTING.md
• Build and test dispatchers: justfile