test-driven-development

Test-Driven Development (TDD)

The Two Gates

Before writing any code, pass it through two gates:

1. The Logic Gate — Triage. Does this piece contain logic?
2. The Iron Rule — For everything that passes the Logic Gate, strict TDD applies.

flowchart TD
    A[New code to write] --> B[Decompose into pieces]
    B --> C{{"Logic Gate: Does this piece contain logic?"}}
    C -->|"Conditionals, transformations, validation, state changes, error handling"| D["Iron Rule: TDD"]
    C -->|"Dataclasses, config, thin wrappers, type aliases, formatting"| E[Write directly]
    D --> F["RED: Write failing test"]
    F --> G["GREEN: Minimal implementation"]
    G --> H["REFACTOR: Clean up"]
    H --> I{More pieces?}
    E --> I
    I -->|Yes| C
    I -->|No| J[Done]

Gate 1: The Logic Gate

Decompose the work into its constituent pieces. For each piece, ask: does this contain logic?

Passes the Logic Gate (requires TDD):

• Conditionals and branching
• Data transformations and computations
• Validation and parsing
• State management and transitions
• Error handling with recovery logic
• Business rules and domain logic
• Algorithm implementations

Does NOT pass the Logic Gate (write directly):

• Dataclasses, NamedTuples, TypedDicts (pure data declarations)
• Type aliases and protocol definitions
• Configuration and constants
• Thin wrappers that only delegate (no branching, no transformation)
• Plot formatting and visual styling
• Boilerplate (__init__.py, module-level setup)
• String templates and static content

When in doubt: If you can't point to a conditional, transformation, or state change, it probably doesn't pass the Logic Gate.

Triage Output

Before writing code, briefly identify what passes and what doesn't:

• "These pieces contain logic and need TDD: X, Y"
• "These are declarations/glue and can be written directly: Z"

Gate 2: The Iron Rule

For code that passes the Logic Gate: never write logic without a preceding failing test.