tdd

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- sage-metadata
cost-tier: sonnet
activation: mandatory
tags: [testing, quality, discipline, implementation]
inputs: [task-spec]
outputs: [implementation, test-suite]
-->

# Test-Driven Development

Write the test first. Watch it fail. Write minimal code to pass. Refactor. Commit.

**The Iron Law:** If *nobody* watched the test fail, you don't know if it tests
the right thing. The failure must have been observed, with evidence. Almost
always that observer is you, this session — see "Inherited red" for the single
narrow case where a prior session already banked the observation. Violating the
letter of these rules IS violating the spirit.

## When to Use

ALWAYS. Every time you write production code. Every feature. Every bug fix. Every
refactor that changes behavior. The urge to skip "just this once" is a rationalization
signal, not a legitimate exception.

## The Cycle

```
RED → VERIFY FAIL → GREEN → VERIFY PASS → REFACTOR → VERIFY STILL PASS → COMMIT → NEXT
```

### Phase 1: RED — Write One Failing Test

Write one minimal test that describes the expected behavior.

Rules:
- Test name describes BEHAVIOR, not mechanism: `rejects expired tokens` not `test auth`
- Test demonstrates the desired API as if writing a usage example
- One assertion per test. If name contains "and" → split it
- Write the assertion FIRST, then work backward to setup

Run the test. It MUST fail. If it passes on first run, the test is suspect —
it's either testing something that already works (useless) or testing the wrong
thing (dangerous). Investigate before proceeding.

The failure must be the RIGHT failure — the test should fail because the feature
doesn't exist yet, not because of a syntax error or wrong import.

### Phase 2: GREEN — Write Minimal Code

Write the SIMPLEST code that makes the test pass. Nothing more.

Rules:
- Do NOT add optional parameters not required by the test
- Do NOT handle edge cases not covered by a test
- Do NOT add "future-proofing" or "nice to have" code
- Do NOT refactor during GREEN — that's the next phase
- The implementation exists ONLY to pass the current test

Run ALL tests. The new test must pass. All existing tests must still pass.
If any test fails, fix it before proceeding. Never leave tests red.

**Lean cadence on resume** (`resume_test_cadence`, default `lean`): on a resume
close-out only, run the **targeted** test(s) for the code you just wrote here,
not the whole suite — the whole suite runs **once** at the close-out verification
(Gate 5), which is where a mid-batch regression is caught. Set
`resume_test_cadence: full`, or on any first-session build, to run ALL tests at
every GREEN as above. The closing full-suite run is never skipped. See
cycle-protocol.md § Resume close-out economy.

### Phase 3: REFACTOR — Clean Up

Now — and ONLY now — you may improve the code. Remove duplication, extract
helpers, rename for clarity, simplify logic.

Rules:
- Do NOT add behavior. Refactoring changes structure, not behavior.
- After EVERY change, re-run ALL tests. They must stay green.
- If a test breaks during refactor, undo and try a smaller refactor.
- Keep tests green. Always.

### Phase 4: COMMIT — Lock It In

Commit with a semantic message referencing what behavior was added.
Then start the next RED cycle for the next behavior.

## Rules — Non-Negotiable

### The Deletion Rule

If production code was written before its corresponding test existed and was
observed failing: **DELETE THE CODE.** Implement fresh from tests only.

Delete means delete. Not "comment out." Not "keep as reference." Delete.
Then write the test. Watch it fail. Then rewrite the code.

This is not punitive. Code written without tests cannot be trusted. The cost
of rewriting with TDD is lower than the cost of debugging code you can't verify.

### The Sunk Cost Trap

"But I already wrote 200 lines!" — Sunk cost fallacy. The time is gone.
Your choice now:
- Delete and rewrite with TDD → takes more time, high confidence
- Keep and add tests after → fast but low confidence, likely bugs

The "waste" is keeping code you can't trust.

### Why Not Tests-After?

Tests written after code answer: "What does this code do?"
Tests written before code answer: "What should this code do?"

Tests-after pass immediately. Passing immediately proves nothing — you never
see them fail, so you don't know if they test the right thing. Tests-after
also test implementation details instead of behavior, making them brittle.

### The Completion Checklist

Before declaring implementation complete, verify ALL of these:

From xoai/sage, MIT.

More from xoai/sage