Make development workflow risk-based and verification proportionate

2026-10-07 17:43:19 -04:00
parent 284fdd638d
commit 0cc0e82bbc
13 changed files with 265 additions and 173 deletions
@@ -0,0 +1,36 @@
+# Proportionate verification
+
+## Choose tests by the changed contract
+
+Cover meaningful behavior, important boundaries, and credible failure modes. Prefer existing test seams and realistic minimal fixtures.
+
+- Unit tests establish logic and regressions through public interfaces.
+- Integration tests establish contracts unit tests cannot, such as persistence or process boundaries.
+- E2E tests establish important user journeys and changed wiring. Avoid replaying every unit-level permutation through the UI.
+- Validate changed UI in its real interface. One realistic scenario may supply both automated and interface-validation evidence when it actually establishes both.
+- Simple straightforward code does not need a test for every branch. Avoid assertions that restate implementation, snapshots of incidental details, and regression tests preserving intentionally removed behavior.
+- For authorized disposable data, verify fresh initialization/reset, representative seed data, and affected behavior. Add historical upgrade/rollback coverage only when data or compatibility must be preserved.
+
+When test infrastructure threatens to become larger than the feature, reassess the seam and failure cost before expanding it. Do not impose a coverage percentage or time cap that leaves consequential behavior untested. Security, valuable data, and broad shared-code changes can warrant more testing than implementation.
+
+## Development and final checks
+
+Run focused checks during implementation and after review fixes. Schedule one full required suite after review/remediation and synchronization, together with applicable static/build checks. Reuse an already completed check instead of running it again merely because a new phase started.
+
+Before a commit, run the checks appropriate to its changes; earlier review commits may rely on focused checks. The final integration boundary still requires the full suite. Repository or CI rules requiring stricter pre-commit checks take precedence. Pure documentation changes may use documentation checks when repository policy permits; executable skill instructions need policy validation, not arbitrary prose snapshots.
+
+## Reuse and invalidation
+
+Record the command, working directory, exit/result, tested commit or tree, and relevant environment/configuration. Evidence is reusable only when the command and relevant code, tests, dependencies, configuration, and environment remain applicable and the process actually completed.
+
+- A commit-only change, record evidence update, or unrelated prose edit does not automatically invalidate product tests. Check documentation links/formatting as applicable.
+- A bounded behavior fix requires affected tests and targeted review. Preserve other results only with an evidence-backed impact assessment.
+- Shared code, dependency/build configuration, conflicting rebases, or uncertain impact require broader checks, including the full suite when its coverage may be affected.
+- If the source branch advanced, inspect the actual delta. Do not equate a new commit ID with changed test inputs, or assume disjoint filenames imply no interaction.
+- Failed, aborted, stale, or environmental checks remain visible. Retry with a reason; never convert a failure to a pass by inference.
+
+“One final full run” removes scheduled duplication, not legitimate reruns after failures or invalidation. If new fixes affect the verified state, rerun the required checks and make the review cover the changed diff before integration.
+
+## External verification gates
+
+Inspect repository scripts, CI requirements, and active hook policy before promising evidence reuse. An exact-command hook may require a standalone full command even when a focused command passes. Its requirements remain binding until explicitly changed or waived under its own policy. Record a waiver as skipped, never passed; avoid routine waivers as a substitute for aligning policy. Scope hook/config changes separately rather than inventing a workflow verification cache.