tdd-workflow

TDD Workflow Skill

Overview

This skill is typically used as part of the broader development workflow managed by the beads plugin (/beads:workflow). TDD is the core implementation practice within Step 3 (Claim & Work) of the beads workflow, providing the requirements → tests → implementation cycle.

---

GOLDEN RULE: Tests Are Grounded in Requirements

Core Principle: Tests are derived from requirements documentation, not implementation details or guesswork.

When implementation doesn't match tests: Implementation is wrong.

When tests seem illogical: Requirements need clarification with the user.

NEVER adjust tests to match code - tests define the contract that code must fulfill.

---

The 4-Step TDD Loop

Step 1: Write Failing Test First

Ground test in requirements:

1. Review requirements documentation for acceptance criteria
2. Identify specific, testable requirement
3. Write test that validates that requirement
4. Run test - verify it FAILS (proving test is actually testing something)

Pattern - Arrange, Act, Assert:

def test_feature_behavior():
    """Test feature behavior.

    Requirement: [Reference to requirement document]
    Given [precondition], when [action], then [expected outcome].
    """
    # Arrange - Set up test conditions from requirements
    input = prepare_test_input()

    # Act - Execute behavior under test
    result = function_under_test(input)

    # Assert - Verify requirement is met
    assert result == expected_value_from_requirements

Verify test FAILS: A test that passes before implementation exists is either:

• Testing nothing (false positive)
• Testing existing code (not new functionality)

---

Step 2: Implement Minimum Code to Pass Test

Write ONLY enough code to make the test pass:

• Implement exactly what requirements specify
• No extra features
• No premature optimization
• No "nice to have" additions

Anti-patterns to avoid:

• Adding features not in requirements
• Optimizing before it works
• Implementing "obvious" future features
• Over-engineering the solution