TDD Workflow

Overview

A strict 7-step TDD cycle that produces high-quality, well-tested code. Each step must be verified and confirmed before proceeding. Status is only updated after real verification

• never hallucinated.

Core principle: RED (failing test) -> GREEN (minimal implementation) -> REFACTOR.

---

Step 0 - Check Existing Progress

At the start of each session, before doing anything else:

• List tdd-summary/ to check for existing step reports (e.g. step-1.md, step-2.md).
• If reports exist, read them to understand prior context, then resume from the next step.

---

Step 1 - Understand Intent

• Explore the codebase for relevant context.
• Derive functional requirements from the available information (user prompt + codebase).
• If any requirement is ambiguous, document the assumption explicitly in step-1.md under an "Assumptions" section rather than asking for clarification.

Write tdd-summary/step-1.md:

# Step 1 - Understand Intent

## Functional Requirements

### FR-1: <title>
<description>

### FR-2: <title>
<description>

## Assumptions

- <any ambiguous point and the assumption made>

---

Step 2 - Write Scenario Docs

For each functional requirement, create a scenario document at docs/scenario/<name>.md:

# Scenario: <Title>
- Given: <precondition>
- When: <action>
- Then: <expected outcome>

## Test Steps

- Case 1 (happy path): <brief description>
- Case 2 (edge case): <brief description>
- Case N: ...

## Status
- [x] Write scenario document
- [ ] Write solid test according to document
- [ ] Run test and watch it failing
- [ ] Implement to make test pass
- [ ] Run test and confirm it passed
- [ ] Refactor implementation without breaking test
- [ ] Run test and confirm still passing after refactor

**IMPORTANT**: Only update above status when a step is confirmed complete. Do not hallucinate.

Invariant: Count of FR = count of scenario documents. Verify before continuing.

Write tdd-summary/step-2.md:

# Step 2 - Write Scenario Docs

## Scenario Documents Created

- FR-1: <title> - `docs/scenario/<name>.md`
- ...

---

Step 3 - Write Failing Test (RED)

For each scenario document:

• Write tests at tests/scenario/test_<name>.py (or equivalent).
• Each scenario must have at least 2 test cases. Add edge cases if missing.
• All acceptance criteria from the scenario document must be covered.
• Tests must not be empty or dummy.
• Update scenario status: check - [x] Write solid test according to document.

After writing, run each test and verify it fails:

• Expected failure (e.g. feature not found, endpoint missing) - this is correct.
  • Update scenario status: check - [x] Run test and watch it failing.
• Unexpected failure (e.g. import error, missing dependency) - fix the environment first.
• Test passes - the feature is not implemented yet; there is no reason it should pass. Fix the test.

Invariant: Count of scenario documents = count of test files. Verify before continuing.

Write tdd-summary/step-3.md:

# Step 3 - Write Failing Test

## Failing Tests Created

- FR-1: <title> - `docs/scenario/<name>.md` - `tests/scenario/test_<name>.py`
- ...

---

Step 4 - Implement to Make Tests Pass (GREEN)

For each failing test:

• Write the minimal production code necessary to make the test pass. Nothing more.
• Do not introduce changes unrelated to the current functional requirement.
• Update scenario status: check - [x] Implement to make test pass.
• Run the test. If it fails, fix the implementation and retry.
• After confirming it passes, update scenario status: check - [x] Run test and confirm it passed.

Write tdd-summary/step-4.md:

# Step 4 - Implement to Make Tests Pass

## Implementations Completed

- FR-1: <title> - `docs/scenario/<name>.md` - Implementation in `<module>`
- ...

All tests now pass. Scenario documents updated.

---

Step 5 - Refactor for Maintainability

For each scenario where tests now pass:

• Improve readability, structure, and maintainability without changing external behavior.
• Update scenario status: check - [x] Refactor implementation without breaking test.
• Run the tests again after refactoring.
  • If tests fail: fix the refactoring. If impossible, rollback to the pre-refactor version.
• After confirming tests still pass, update scenario status: check - [x] Run test and confirm still passing after refactor.

Write tdd-summary/step-5.md:

# Step 5 - Refactor for Maintainability

## Refactorings Completed

- FR-1: <title> - `docs/scenario/<name>.md` - <what was improved>
- ...

All tests still pass after refactoring. Scenario documents updated.

---

Step 6 - Regression Test

Run the complete test suite (all tests, not just those added in this session):

• If regression occurs in unrelated tests:
  • Analyze the failure and understand its impact on existing functionality.
  • Fix the implementation to restore all passing tests.
  • Re-run the complete suite until everything passes.

NEVER modify existing tests that are unrelated to the current functional requirements.

Write tdd-summary/step-6.md:

# Step 6 - Regression Test

## Regression Test Results

- Complete test suite executed: `<command>`
- All tests pass: Yes / No
- If regression found: <brief description of fix applied>

---

Step 7 - Final Review

Verify that every scenario document has all status checkboxes checked.

Review:

• Every FR has a corresponding scenario document and test file.
• All tests pass and code is clean.

Write tdd-summary/step-7.md:

# Step 7 - Final Review

## Summary

- Functional requirements addressed:
    - FR-1: ...
- Scenario documents: `docs/scenario/...`
- Test files: `tests/scenario/...`
- Implementation complete and all tests passing after refactoring.

## How to Test

Run: `<test command>`

Finally, archive the summary folder:

mv tdd-summary/ completed-tdd-archives/tdd-$(date +%Y%m%d-%H%M%S)

TDD workflow complete.

---

Iron Rules

• Do not skip steps. Each step must be verified before the next begins.
• Do not edit tests during implementation or refactor steps, unless the test itself was obviously written incorrectly in Step 3.
• Do not hallucinate status. Only check a status checkbox after real, confirmed verification.
• Keep counts equal. FR count = scenario doc count = test file count at all times.
• Step gates: If running interactively, present each step report and wait for confirmation before continuing. If running as a delegated subagent, proceed automatically through all steps.
• If changes are requested at any step, loop back to the appropriate step and adjust all downstream artifacts accordingly.