Test-Driven Development Skill Skill

Test-Driven Development Skill

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

The Cycle

    ┌──────────────────────────────────────────┐
    │                                          │
    ▼                                          │
┌───────┐    ┌───────┐    ┌──────────┐        │
│  RED  │ ──▶│ GREEN │ ──▶│ REFACTOR │ ───────┘
└───────┘    └───────┘    └──────────┘
Write test   Make pass    Clean up
Watch FAIL   Minimal code  Keep green

RED Phase

What to Do

Write a single failing test
Run the test
Watch it fail
Verify failure is for expected reason

Why "Watch It Fail" Matters

| Without Watching Fail | With Watching Fail | |-----------------------|-------------------| | Test might always pass (bug in test) | Confirms test can fail | | Test might fail for wrong reason | Confirms test checks right thing | | No proof test validates behavior | Evidence of validation |

Red Phase Checklist

[ ] Test written for ONE behavior
[ ] Test run
[ ] Test failed
[ ] Failure is for expected reason (not typo, import error, etc.)

GREEN Phase

What to Do

Write the minimum code to pass the test
Run the test
Watch it pass
Nothing more - no extras, no "while I'm here"

What Minimum Means

| Too Much | Minimum | |----------|---------| | Add error handling for edge cases | Just make this test pass | | Refactor related code | Just make this test pass | | Add features "we'll need" | Just make this test pass |

Green Phase Checklist

[ ] Only code needed for this test written
[ ] Test run
[ ] Test passed
[ ] No other tests broken

REFACTOR Phase

What to Do

Clean up the code
Run ALL tests after each change
Keep everything green
Stop when code is clean

Safe Refactorings

Rename for clarity
Extract methods/functions
Remove duplication
Improve structure

Refactor Phase Checklist

[ ] Code is clean
[ ] All tests still pass
[ ] No new behavior added

Non-Negotiable Rules

[!CRITICAL] These are not guidelines. They are rules.

Rule 1: Test First

Production code written BEFORE failing test → DELETE and restart

No exceptions. No "I'll write the test after." That's not TDD.

Rule 2: Watch It Fail

Test not seen failing → Test not trusted

Running the test and seeing green immediately means something is wrong.

Rule 3: Minimal Green

Code beyond minimum → Remove it

YAGNI (You Aren't Gonna Need It). Add it when a test requires it.

Rule 4: Keep Tests Green

Refactoring breaks tests → Undo and retry smaller

Refactoring should never change behavior.

Integration with Verification

TDD is a specialized form of the verification skill:

| Verification Step | TDD Equivalent | |-------------------|----------------| | IDENTIFY | Write the test | | RUN | Execute the test | | READ | Observe failure/pass | | VERIFY | Expected behavior? | | CLAIM | Only after green |

Integration with Writing-Plans

Plans should include TDD structure:

## Task N: [Name]

1. Write failing test:
   ```typescript
   [complete test code]

Run test:
```
[command]
```
Expected: FAIL with "[message]"
Implement:
```
[complete implementation]
```
Run test: Expected: PASS


---

## Deviation Logging

Code without test logged:

```yaml
- id: [auto]
  timestamp: [now]
  expected: "Failing test written before implementation"
  actual: "Implementation written without test"
  root_cause: untested_code
  fix: |
    Enforce TDD skill for all code tasks.
    Add test-first check to orchestration.

Common TDD Mistakes

| Mistake | Problem | Fix | |---------|---------|-----| | Writing test after code | Can't verify test catches bugs | Delete code, write test first | | Not watching test fail | Don't know if test works | Run test before implementation | | Making multiple tests pass at once | Can't isolate failures | One test at a time | | Refactoring while red | Changes behavior | Get green first | | Testing implementation details | Brittle tests | Test behavior, not code |

Agent Skills: Test-Driven Development Skill

Install this agent skill to your local

Skill Files