test-driven-development

name	test-driven-development
description	Use this implementation mechanic for new behavior or bug fixes requiring test coverage only when explicitly invoked by name or called by an active Gambit workflow owner; do not select it implicitly as a peer workflow.

Codex Backend

This skill is assembled for Codex. Before following the workflow, read references/codex-backend.md completely. Its operation mappings are binding: SessionPlanRead reads the root session's native wave plan, SessionPlanWrite mutates it only through update_plan, and SessionContextRead reads the same root transcript. One native plan step is one Gambit wave; parallel workers are subagent threads inside that single step. These are backend operations, not literal shell commands.

Test-Driven Development

Overview

Write the test first. Watch it fail. Write minimal code to pass. Refactor. Commit.

Core principle: If you didn't watch the test fail, you don't know if it tests the right thing.

Rigidity Level

LOW FREEDOM — Follow these exact steps in order. Do not adapt, skip, or reorder.

Violating the letter of the rules is violating the spirit of the rules.

Quick Reference

Phase	Action	Expected Result
RED	Write one failing test	Test FAILS with expected message
Verify RED	Run test, read failure	Fails because feature missing (not typo)
GREEN	Write minimal code	Test passes
Verify GREEN	Run ALL tests	All green, no regressions
REFACTOR	Clean up while green	Tests still pass
COMMIT	Commit the increment	Behavior captured

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Wrote code before the test? Delete it. Start over.

• Don't keep it as "reference"
• Don't "adapt" it while writing tests
• Don't look at it
• Delete means delete

Fresh implementation from tests. No exceptions.

When to Use

Always when writing production code:

• New features or functions
• Bug fixes (test reproduces the bug first)
• Behavior changes during refactoring
• Any code that should have test coverage

Exceptions (confirm with your human partner):

• Throwaway prototypes (will be deleted)
• Generated code (output, not generators)
• Configuration files

TDD vs Executing-Plans

These skills are complementary, not competing:

	TDD	Executing-Plans
Scope	Single function or behavior	Multi-task epic
Controls	HOW code is written	WHICH task, WHEN to stop
Cycle	RED → GREEN → REFACTOR → COMMIT	Load → Execute → Checkpoint → STOP
Checkpoints	After each test passes	After each task completes
Relationship	Called BY executing-plans	Calls TDD during execution

TDD is a coding discipline used WITHIN task execution. Executing-plans decides WHAT to build; TDD decides HOW to build it.

The Process

1. RED — Write One Failing Test

Write a single test for one behavior. Not two. Not "and."

Requirements:

• Test ONE behavior ("and" in name? Split it)
• Name describes the behavior: test_rejects_empty_email, not test_email
• Use real objects, not mocks (unless external dependency)
• Assert on behavior, not implementation details

Run the test. Read the failure message.

Confirm ALL THREE:

• Test fails (not errors with syntax issues)
• Failure message matches expectation ("function not found" or assertion mismatch)
• Fails because feature is MISSING, not because of typos

If test passes immediately: Your test is wrong. It tests existing behavior, not new behavior. Fix the test before continuing.

If test has syntax errors: Fix syntax, re-run until you get a proper assertion failure.

2. GREEN — Write Minimal Code

Write the simplest code that makes the test pass. Nothing more.

Minimal means:

• No features the test doesn't exercise
• No error handling the test doesn't check
• No type annotations the test doesn't require
• No docstrings or comments
• Hardcoded values are fine if only one test exercises the case

Run ALL tests (not just the new one). Confirm:

• New test passes
• All existing tests still pass
• No warnings or errors

If new test fails: Fix code, not test. If other tests break: Fix regressions NOW, before continuing.

3. REFACTOR — Clean Up While Green

Only after ALL tests pass:

• Remove duplication
• Improve names
• Extract helpers if repeated
• Simplify logic

Run tests after each refactoring change. If tests break, undo the refactoring step.

Do NOT add behavior during refactoring. No new features, no new edge cases. Those are new RED cycles.

4. COMMIT — Capture the Increment

git add [test file] [implementation file]
git commit -m "feat(module): [behavior description]"

Commit message describes the behavior, not the test.

5. REPEAT

Next behavior → next failing test → next minimal implementation.

Each RED-GREEN-REFACTOR-COMMIT cycle should be small — one behavior at a time.

Bug Fix Workflow

Bug fixes follow TDD too. The test reproduces the bug.

1. RED: Write test that exercises the buggy input/behavior
2. Verify RED: Run test — confirms the bug exists (test fails)
3. GREEN: Fix the bug with minimal change
4. Verify GREEN: Run ALL tests — bug fixed, no regressions
5. COMMIT: The regression test permanently guards against this bug

Example: Feature with TDD

Task: Add email validation that rejects empty strings and missing @ symbols.

RED:

def test_rejects_empty_email():
    result = validate_email("")
    assert result is False

Verify RED:

$ pytest -k test_rejects_empty_email
FAILED: NameError: name 'validate_email' is not defined

Good — fails because function doesn't exist.

GREEN:

def validate_email(email):
    if not email:
        return False
    return True

Minimal. Only handles the case the test checks.

Verify GREEN:

$ pytest
4 passed

Next RED (new behavior):

def test_rejects_missing_at_symbol():
    result = validate_email("userexample.com")
    assert result is False

Verify RED → GREEN → Verify GREEN → REFACTOR → COMMIT → REPEAT.

When Stuck

Most TDD friction is a design signal, not a testing problem. Use this table to translate the symptom into the actual issue:

Symptom	What it usually means	Action
Don't know how to write the test	The API you want doesn't exist yet	Write the wished-for API as the test first — assertion before implementation. Design from the caller's side.
Test feels too complicated	The design is too complicated	Simplify the interface before writing the test. Complex tests track complex code.
Must mock everything	Code is too tightly coupled	Apply dependency injection. Mocking-everywhere means the unit isn't really a unit.
Test setup is huge	Design is doing too much per object	Extract helpers. If extraction doesn't shrink setup, simplify the design itself.
Test passes immediately	Test doesn't exercise the new behavior	Rewrite the test. It's checking something already true.
Can't decide what to test first	Start with the happiest single path — one assertion. Edge cases are separate RED cycles.	—

If none of these apply and you're still stuck, the problem is usually that the behavior isn't clearly defined yet — go back to the plan or epic and sharpen the requirement before writing code.

Testing Anti-Patterns

Never Test Mock Behavior

BAD:  assert mock.was_called()        # Tests plumbing, not behavior
GOOD: assert result == expected_value  # Tests actual output

Never Add Test-Only Code to Production

BAD:  def reset(self): ...  # Only used in tests, dangerous in prod
GOOD: Test utilities handle setup/teardown externally

Never Mock Without Understanding

Before mocking any dependency:

1. What side effects does the real code have?
2. Does this test depend on those side effects?
3. If yes → mock at a lower level, not this method

Red Flags — STOP and Start Over

• Wrote code before test
• Test passes immediately
• Can't explain why test failed
• Adding features during GREEN beyond what test requires
• Tests added "later"
• Rationalizing "just this once"
• "I already manually tested it"
• "Keep as reference" or "adapt existing code"
• "Already spent X hours, deleting is wasteful"
• "This is different because..."

All of these mean: Delete code. Start over with RED.

Common Rationalizations

Excuse	Reality
"Too simple to test"	Simple code breaks. Test takes 30 seconds.
"I'll test after"	Tests passing immediately prove nothing.
"Already manually tested"	Ad-hoc ≠ systematic. Can't re-run.
"Deleting X hours is wasteful"	Sunk cost. Unverified code is debt.
"Need to explore first"	Fine. Throw away exploration, start with RED.
"Test is hard to write"	Hard to test = hard to use. Simplify the design.
"TDD slows me down"	TDD is faster than debugging in production.
"This is different because..."	It's not. RED-GREEN-REFACTOR.

Language-Specific Commands

See REFERENCE.md for test runner commands by language (Go, TypeScript, Rust, Python, Ruby, etc.).

Verification Checklist

Before marking work complete:

• Every new function/method has a test
• Watched each test fail before implementing
• Each test failed for expected reason (feature missing, not typo)
• Wrote minimal code to pass each test (no extras)
• All tests pass with no warnings
• Tests use real code (mocks only if unavoidable)
• Edge cases covered as separate RED-GREEN cycles
• Changes committed after each green cycle

Can't check all boxes? You skipped TDD. Start over.

Integration

Called by:

• gambit:executing-plans (when implementing task steps)
• gambit:debugging (write failing test reproducing bug)

Calls:

• gambit:verification (running tests to verify RED and GREEN)

Workflow:

RED (write test) → Verify fail → GREEN (minimal code) → Verify pass → REFACTOR → COMMIT → REPEAT