Agent Guidance

Repository orientation

Follow task-specific and repository-specific instructions before this file.
Before editing, inspect the relevant implementation, tests, configuration, and similar code.
Reuse established patterns and repository tooling; do not introduce a second convention.
Do not manually edit generated files when an authoritative source or generator exists.

Prefer nix develop for an interactive shell.
Prefer nix develop -c <command> for repository commands.
Change flake.nix or flake.lock only when the development toolchain itself intentionally changes.

Keep changes narrowly scoped to the task.
Favor straightforward existing abstractions over speculative generalization.
Preserve public behavior unless the task intentionally changes it.
During intentional cutovers, remove obsolete code instead of adding compatibility shims.
Preserve or improve existing type safety; use type annotations for new or changed code.
Document public caller-facing entities such as modules, fields, methods, functions, parameters, classes, data types, interfaces, errors, and special values.
Prefer documentation on individual members to documenting at the class level, and avoid duplication.
Docstrings must describe behavior relevant to users and callers of the entity, not implementation details.
Docstrings should briefly describe any special values.
Make error behavior explicit. Do not swallow errors or suppress warnings to make checks pass.
Avoid unrelated refactoring or formatting churn.
Add dependencies only when clearly required.
Do not invent product requirements or compatibility guarantees not supported by the task or repository.

Add focused coverage for behavior changes and regression tests for bug fixes where practical.
Test observable behavior, boundaries, and errors rather than implementation details.
Keep tests focused and follow existing test patterns.
Every bug fix needs a regression test that fails before the fix.
Test observable behavior, boundaries, and error cases rather than implementation details.
Follow Arrange / Act / Assert and comment these phases in each unit test.
While iterating, run the narrowest relevant checks first.
Treat formatter, linter, type-checker, test warnings, and failures as work to resolve rather than suppress.
Before completion, run the relevant formatter, linter, type checker, tests, and build/code-generation checks.
Resolve new warnings and failures rather than suppressing them.
Review the final diff for unrelated changes, stale code, debugging artifacts, and inconsistent documentation or call sites.
If a relevant check cannot be run, state that explicitly.