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 test pass. - If Rust code changed, run `cargo fmt --all -- --check` and `just test-rust`. - If Python code or a Python-facing adapter changed, run `just test-python`. - If the TypeScript adapter contract or one of its source schemas changed, run `just test-typescript`. - If `crates/fabric-core` changed in a way exposed through Python, run both the Rust and Python suites. - If the PyO3 bridge or package metadata changed, run `just build-python` and `cargo check -p fabric-python --locked`. - If public configuration types changed, confirm the schema snapshot tests in `just test-rust` pass and review generated schema diffs. - If an adapter or integration changed, run its focused tests. - If a Cargo or Python manifest or lockfile changed, run `uv run --no-project python scripts/licensing/license_diff.py --base-ref origin/main`, review the transitive license changes, then run the `attributions-rust` and `attributions-python` pre-commit hooks. - If the TypeScript manifest or npm lockfile changed, inspect the complete npm dependency tree and license fields, confirm the package still has zero production dependencies, run the `attributions-node` pre-commit hook, and run its package and audit checks. - If documentation or examples changed, run `just docs` when practical and verify documented commands against the current repository. - If code changes alter APIs, commands, paths, packaging behavior, telemetry semantics, or documented best practices, update dependent maintainer skills in the same branch. Because the consumer skills under `skills/` restate SDK guide, Pydantic model, and Rust type details, update them in parity whenever those surfaces change. ## Start With the Change Shape - **Rust core, CLI, or shared runtime semantics changed** Run Rust formatting and tests. Add Python tests when the behavior is exposed through the SDK, and run relevant tests for CLI behavior. - **Python SDK or PyO3 binding changed** Use `python-tests`, run focused pytest tests first, then run `just test-python`. Rebuild with `just build-python` when native code or packaging changed. - **Adapter behavior changed** Run the focused adapter tests under `tests/adapters`, then `just test-python`. - **Harbor integration changed** Run `tests/integrations/test_harbor_runner.py` and `tests/python/test_adapter_capabilities.py`, then `just test-python`. For host admission changes, verify metadata inspection without harness SDKs or task discovery, selected telemetry claims, and task-side descriptor drift rejection before startup. - **Schema or public contract changed** Run the Rust, Python, and TypeScript suites and review changes under `schemas/`, the checked-in Python adapter-contract representations, generated TypeScript sources, and generated API references. - **Documentation-only change** Use `contribute-docs` and `review-doc-style`. Run `just docs` for docs-site or generated-reference changes. - **CI or packaging changed** Use `maintain-ci` or `maintain-packaging`, then run the recipes and checks whose behavior changed. ## Core Validation Matrix ```bash just test-rust just test-python just test-typescript ``` ## Common Targeted Commands ```bash # Rust just build-rust just test-rust cargo fmt --all -- --check cargo check -p fabric-python --locked # Python and native extension just build-python just test-python uv run --no-sync pytest -k "<pattern>" # TypeScript adapter contract just build-typescript just test-typescript just pack-typescript # Documentation just docs # Dependency licenses uv run --no-project python scripts/licensing/license_diff.py --base-ref origin/main uv run pre-commit run --all-files attributions-rust uv run pre-commit run --all-files attributions-python uv run pre-commit run --all-files attributions-node # Justfile and patch hygiene just --fmt --check git diff --check ``` ## Hygiene Checks Before review or handoff: - Verify README and docs entry points still match current package names and paths. - Verify examples use current `just` recipes and public commands. - Call out checks that were not run and why. - Run `git diff --check`. ## References - Python test guidance: `python-tests` - Build and test recipes: `justfile` - Python CI: `.github/workflows/ci_python.yml` - Rust CI: `.github/workflows/ci_rust.yml` - TypeScript CI: `.github/workflows/ci_typescript.yml` - Documentation CI: `.github/workflows/fern-docs.yml` - Public Python contract: `docs/python-sdk-contract.md` - Public adapter contract: `schemas/SCHEMA.md`