Test-driven development
NO NEW OR CHANGED OBSERVABLE BEHAVIOUR WITHOUT A RIGHT-REASON FAILURE FIRST
Never delete or overwrite unknown, pre-existing or user-authored work to create a red state. If this run wrote production code before the test, preserve its patch, remove only the exact run-owned hunks when authorised, witness the right-reason failure, then reapply and minimise them. Existing code gets a regression or characterisation seam before repair. Deliberate throwaway prototypes, generated code and configuration may use an explicitly recorded exception; deadline pressure is not one.
Red -> green -> refactor
- Red: write one test for one observable behaviour through the public interface. Name it like a specification. Run it and confirm it fails because the behaviour is missing, not from setup, import or typo. A test that passes immediately needs sharpening.
- Green: write only the simplest production change that passes. Avoid speculative options and unrelated cleanup. Run the focused test each cycle, affected checks at tranche boundaries, and the full required suite at the enclosing verification gate; output must be clean.
- Refactor: only while green, remove duplication, improve names and deepen modules. Rerun tests after each structural step.
Work vertically: test -> implementation -> repeat. Start with one tracer bullet through the full path, then add behaviours from what each cycle reveals. Never write an imagined horizontal test batch before implementation. Prioritise critical paths and complex logic.
Test boundaries
Test what callers observe, not private methods, internal call order or data shape. A valid test survives an internal refactor. Verify outcomes through the public interface rather than querying side channels. See tests.md.
Mock only system boundaries: external APIs, time/randomness and, when needed, filesystem/database. Never mock owned internal collaborators to make a test pass; inject a narrow boundary instead. See mocking.md and interface-design.md.
Hard-to-test code is design evidence: accept dependencies, return results instead of hiding effects, and prefer deep modules with small interfaces. On green, use deep-modules.md and refactoring.md; do not smuggle redesign into green.
Cycle gate
Before the next behaviour confirm: public observable contract; witnessed right-reason failure; minimal passing code; focused and broader checks green; no dirty output; and resilience to internal refactoring.
For a bug, first reproduce the exact failure as the regression test, watch it
fail, then repair and watch it pass. If no correct seam reaches the bug, route
to diagnose; do not bless a shallow test. implement owns independent review,
repair loops, documentation and human acceptance.