testing

Investigate First

A failing test signals one of two things:

1. The test is wrong — outdated expectations, flaky setup, incorrect assertions
2. The code is broken — regression, missing edge case, integration failure

Don't assume. Read the failure, trace the code path, determine which is true before changing anything.

Common signs the test is wrong:

• Assertions don't match documented behavior
• Test relies on implementation details that changed intentionally
• Flaky failures that pass on retry

Common signs the code is broken:

• Test matched previously working behavior
• Multiple tests fail in related areas
• Error messages indicate actual bugs (null refs, type errors, missing data)

TDD

When adding new functionality, write tests first:

1. Red — Write a failing test that specifies the behavior
2. Green — Write minimal code to pass the test
3. Refactor — Clean up while tests stay green

Benefits:

• Forces you to clarify requirements before coding
• Prevents over-engineering (you only write what's needed)
• Catches regressions immediately

Skip TDD when: fixing obvious bugs, exploratory prototyping, or when the test setup cost exceeds the implementation.

Delegating Test Fixes

When using agents to fix test failures:

1. Agent makes the fix and exits — no test execution
2. Orchestrator runs tests after agent returns
3. Repeat if failures remain

Why agents don't run tests:

• Prevents chasing cascading failures
• Avoids wasted context on test output parsing
• Forces agents to report blockers instead of attempting workarounds

In agent instructions, include:

Fix the failing test. Do NOT run the test suite—make your change and exit.

If an agent encounters ambiguity about whether to fix the test or the code, it should stop and report a blocker.

Before Fixing

• [ ] Read the failure message and stack trace?
• [ ] Identified whether test or code is wrong?
• [ ] Understand the expected vs actual behavior?

If no, keep investigating.