TDD Discipline
Relevant source files
The following files were used as context for generating this wiki page:
Test-Driven Development (TDD) Discipline enforces a strict "test-first" methodology for all production behavior changes. The core rule requires one behavior-specific RED state before any production code changes occur. This discipline ensures that every modification to the system is driven by a verifiable requirement and that existing behavior remains preserved through real production interfaces.
Sources: skills/tdd/SKILL.md:1-12, skills/production-code/SKILL.md:12-16
Core Methodology
The TDD process operates through a series of atomic vertical slices. Each slice involves establishing a failure (RED), implementing the minimum code to satisfy the requirement (GREEN), and optionally improving the structure (REFACTOR).
The Red-Green-Refactor Cycle
- RED: You write a test for an atomic behavior through a recorded Seam. The test must fail with a specific
redFailuremarker, which can be an assertion or a product-specific exception. - GREEN: You write the smallest possible production change to pass the test. You do not anticipate future requirements during this phase.
- REFACTOR: After all contract items are GREEN, you may refactor the code. You rerun all tests after each step to ensure no regressions occur.
Sources: skills/tdd/SKILL.md:68-87, skills/tdd/SKILL.md:111-115
TDD Execution Flow
This diagram illustrates the standard workflow for a single behavior slice within the TDD discipline.
The Behavior Map
The Behavior Map is the authoritative record of proof obligations. It is initially created during the Production Preflight phase and updated as implementation reveals new consequences.
Map Item Structure
Each item in the Behavior Map contains specific metadata to track its lifecycle and verification status.
| Field | Description |
|---|---|
id | Stable uppercase identifier (e.g., BM_SUCCESS_PATH). |
kind | contract (new behavior) or preservation (existing behavior). |
behavior | Description of the observable outcome under a specific precondition. |
seam | The public Interface or boundary where behavior is observed. |
redFailure | The specific marker or exception expected during the RED phase. |
status | Current state: pending, red, green, already-satisfied, withdrawn, or superseded. |
Sources: skills/tdd/SKILL.md:46-66, skills/production-preflight/SKILL.md:126-140
Mapping Requirements
You must create map items for:
- Every contract-declared success, error, and exception.
- Meaningful state transitions and rejected transitions.
- Material guarantees at wrapped or rerouted Seams (success, failure, atomicity).
- Interactions where one behavior might invalidate another.
- Load-bearing assumptions requiring semantic falsification.
Sources: skills/tdd/SKILL.md:37-44
Testing Principles and Constraints
TDD Discipline enforces high-fidelity testing through real production boundaries.
The Mock Ban
The discipline strictly forbids the use of mocks. You must never create a test-only proof path or substitute an interior path. All tests must drive the real production Interface.
Sources: skills/tdd/SKILL.md:20-22, skills/production-code/SKILL.md:95-96
Seams and Attack Vector Tests (ACT)
A Seam is the public Interface or externally observable product boundary. An Attack Vector Test (ACT) is a production test that drives a real Seam, states an expected result, and compares it with the observed outcome.
- Runner-backed ACT: Direct invocation via test runners (pytest, unittest).
- Non-runner ACT: CLI commands, scripts, or end-to-end operations.
Sources: skills/tdd/SKILL.md:13-19, skills/tdd/SKILL.md:28-30
Differential Testing
When one evaluation system produces a value and another decides its validity, you use differential testing. This involves executing the same input through two systems or configurations and comparing the outputs.
Sources: skills/tdd/SKILL.md:42, skills/diagnose/SKILL.md:38-39
Workflow Integration
TDD is a governed phase within the repo-production-workflow. It interacts with implementation and verification steps to ensure continuity.
Verification and Completion
TDD is considered complete only when specific criteria are met:
- Every
contractitem isgreen,baseline, orwithdrawn. - Every
preservationitem isgreen,already-satisfied, oromittedwith evidence. - No proof gaps remain.
- The broader relevant test suite passes.
- No behavior-changing edits occurred after the last GREEN result.
Sources: skills/tdd/SKILL.md:117-122, skills/repo-production-workflow/SKILL.md:195-204
TDD Discipline provides a structured framework for ensuring software quality by anchoring implementation in verifiable behavioral outcomes. By enforcing the mock ban and requiring real Seam interaction, it guarantees that tests serve as accurate proxies for production behavior.