Skip to content

Find code by asking what it does. A CLI for coding agents that uses Jev to discover relevant files and source context.

skills: catch regressions end to end; unit tests only where they speed iteration

David Zhang28cf384d444e
diff --git a/.agents/skills/audit-agents/assets/example-agents.md b/.agents/skills/audit-agents/assets/example-agents.md
index 6b7da71..e5a4623 100644
--- a/.agents/skills/audit-agents/assets/example-agents.md
+++ b/.agents/skills/audit-agents/assets/example-agents.md
@@ -24,6 +24,8 @@ A change that reaches the whole system does not bring that run forward on its ow
Every expensive run must answer a question a cheaper one can't. <Name this product's expensive runs>; do only the ones a change can move. Reuse a result that is still valid, and rerun only what a change could have invalidated. Docs and data that no code reads need no run at all.
+Default to end-to-end or system-level tests for regression coverage; use a unit test only for specific, complex business logic when fast feedback will materially speed development.
+
Write the test first. Before changing behaviour or fixing a bug, invoke <skill: write-tests> and follow its red/green workflow. Test what the product does and how it fails, not how the code is shaped.
A change that shouldn't alter behaviour (a refactor, a performance change) must leave the output unchanged, or be a named decision.
diff --git a/.agents/skills/code-review/SKILL.md b/.agents/skills/code-review/SKILL.md
index 7c41122..ed73739 100644
--- a/.agents/skills/code-review/SKILL.md
+++ b/.agents/skills/code-review/SKILL.md
@@ -93,7 +93,7 @@ The most valuable test suite is the one most decoupled from the implementation i
- **A passing test should mean a real user gets the right result.** If a test can pass while the production path is broken, the test is wired wrong. Common smells: stubbing the thing under test, bypassing the router/dispatcher/parser, hand-constructing internal events that production would have built from input.
- **Harnesses must wire the system the way production wires it.** Optional inputs that are always set in practice are part of the contract — pass equivalents in the harness (e.g. a settled status stream, the modal config, the same env vars). If you found a bug only by running against a real environment, the harness skipped something production sets; fix the harness so the next regression in the same shape is caught by the test suite, not by a user.
- **Coupled tests are a refactor tax.** When renaming an internal function or moving a module breaks dozens of tests without changing any user-visible behavior, the suite is testing the wrong layer. Rewrite those tests against the outer surface and delete the brittle ones.
-- **Reserve unit tests for genuinely tricky pure logic** — parsers, normalizers, schedulers, state machines with subtle invariants. Everything else earns more value as an integration or end-to-end test.
+- **Default to end-to-end or system-level regression tests.** Use a unit test only for specific, complex business logic when fast feedback will materially speed development.
## 13. A failing check can be a toolchain defect, not a code defect
diff --git a/.agents/skills/implement-spec/SKILL.md b/.agents/skills/implement-spec/SKILL.md
index 3440bb9..c6e101a 100644
--- a/.agents/skills/implement-spec/SKILL.md
+++ b/.agents/skills/implement-spec/SKILL.md
@@ -33,7 +33,7 @@ depends on prior work.
replace it with the simpler architecture and update the spec handoff.
3. Implement one coherent pass: usually one slice, one vertical checkpoint, or
one architecture correction. Keep the review surface small enough to audit.
-4. Verify the actual contract. For behavior changes, run the focused unit tests
+4. Verify the actual contract. For behavior changes, run the focused tests
first; for browser-visible work, use the real browser/harness and inspect
screenshots so the subject is framed and readable, not merely nonblank.
A visual CHANGE carries two extra proofs before you claim it: a
diff --git a/.agents/skills/write-tests/SKILL.md b/.agents/skills/write-tests/SKILL.md
index 38ed5c3..14741d4 100644
--- a/.agents/skills/write-tests/SKILL.md
+++ b/.agents/skills/write-tests/SKILL.md
@@ -10,6 +10,8 @@ refactor or config change that preserves it. Most bad tests fail the opposite
way: red on harmless changes, green while the real path is broken. Every rule
below serves that one goal.
+Default to end-to-end or system-level tests for regression coverage; use a unit test only for specific, complex business logic when fast feedback will materially speed development.
+
For deciding whether coverage adds independent proof, where it belongs, or
which existing tests can go, use [audit-tests](../audit-tests/SKILL.md).
@@ -35,8 +37,8 @@ which existing tests can go, use [audit-tests](../audit-tests/SKILL.md).
which internal functions ran or how a value is computed. A test on the public
surface survives a rewrite of everything underneath; a test that reaches into
internals breaks on every refactor and pins implementation, not behavior.
- Reserve isolated unit tests for genuinely tricky pure logic (parsers,
- schedulers, state machines).
+ Use an isolated unit test only when the logic is specific and complex enough
+ that its faster feedback will materially speed development.
- **Nothing the compiler already guarantees.** A test that re-asserts a type
signature — field shapes, rejected argument types — can only fail if the
compiler failed first. Spend the budget on business rules, arithmetic,
@@ -44,9 +46,8 @@ which existing tests can go, use [audit-tests](../audit-tests/SKILL.md).
- **Actual values, not collection sizes.** For dedup/normalize/idempotency
paths, `length == 1` passes even when normalization is broken; also assert
the stored value equals the expected canonical form.
-- **The smallest scale that can show the behavior.** Two entities and one
- mechanism before crowds and integration; small tests fail fast with readable
- state and don't entangle five behaviors in one assert.
+- **Keep system scenarios small.** Use the minimum data and mechanisms needed
+ to prove the end-to-end behavior without entangling unrelated claims.
- **The design contract, not current behavior.** When a test goes red, the
reflex is to re-measure and pin the new number — resist it: a bar calibrated
to whatever the code currently does silently encodes bugs as baseline. Write
diff --git a/AGENTS.md b/AGENTS.md
index b81e5f6..b0ac195 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -24,6 +24,8 @@ A change that reaches the whole system (the retrieval pipeline, the response a c
Every expensive run must answer a question a cheaper one can't. Benchmark runs, which spend real money, and the container tests of the installed package are the expensive runs here; do only the ones a change can move. Reuse a result that is still valid, and rerun only what a change could have invalidated. Docs and data that no code reads need no run at all.
+Default to end-to-end or system-level tests for regression coverage; use a unit test only for specific, complex business logic when fast feedback will materially speed development.
+
Write the test first. Before changing behaviour or fixing a bug, invoke [`write-tests`](.agents/skills/write-tests/SKILL.md) and follow its red/green workflow. Test what the product does and how it fails, not how the code is shaped.
A change that shouldn't alter behaviour (a refactor, a performance change) must leave the output unchanged, or be a named decision.