Test-Driven Development
Use this skill when implementing any feature, bugfix, or behavior change that requires confidence that the code works as intended. TDD is the practice of writing a failing test first, then writing minimal production code to pass it, then refactoring.
Use this skill when
- Implementing any new feature or functionality.
- Fixing a bug or addressing a regression.
- Refactoring or improving existing code.
- Adding edge-case handling or boundary-condition logic.
- You need to ensure code behavior is correct and documented through executable tests.
Do not use this skill when
- The task is documentation-only or configuration-only with no executable logic.
- The request is exploratory research or one-off investigation without production code output.
- The repository explicitly prohibits or does not support automated testing (rare; ask first).
Iron Law
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
Write the test. Watch it fail. Write minimal code to pass. Never write production code without a failing test first.
Tests are specifications. They answer "what should this code do?" Tests written after are archaeology; they can only answer "what does this code do?"
Routing boundary
| Scenario |
Use TDD Skill |
Route Away |
| New feature request |
Yes — write test for the desired behavior first |
N/A |
| Bug report |
Yes — write test that reproduces the bug, then fix |
Consider github-actions-failure-triage if it's a CI failure |
| Refactor request |
Yes — write test for current behavior, refactor while keeping tests green |
Consider typescript-any-eliminator or other targeted hardening skills for narrower improvements |
| Code review feedback |
Yes if feedback requests behavior change or new handling |
Use review-comment-resolution for process; route back to TDD for code changes |
| Performance optimization |
Yes — write benchmark test first, then optimize, keep tests green |
N/A |
| Configuration or docs only |
No |
Document without this skill |
Inputs to gather
Before starting, clarify:
- What is the expected behavior? (What should the code do?)
- What test framework is in use? (Jest, Mocha, Vitest, Go testing, etc. — check repo defaults)
- What is the scope? (One function? A whole module? Incremental delivery?)
- Are there existing tests that establish patterns or conventions?
- What are the acceptance criteria? (Happy path? Edge cases? Error handling?)
First move
- Do not write production code yet.
- Write one minimal failing test that asserts the desired behavior.
- Run the test and confirm it fails for the right reason (e.g., "function does not exist" or "returned undefined", not a syntax error).
- Only then move to the RED-GREEN-REFACTOR cycle.
The test failure is your proof that the feature does not exist yet. This is the RED phase.
Workflow
RED: Write one minimal failing test for the specific behavior. Confirm it fails for the right reason (feature missing, not syntax error).
- One assertion or one logical outcome per test when possible.
- Use a test name that says what you expect:
should return 42 when input is valid not should work.
GREEN: Write the simplest code that makes the test pass. No extra features, no YAGNI (You Aren't Gonna Need It).
- Minimal. If the test wants a function that returns 42, return 42 (not dynamic logic yet).
- Ignore performance, elegance, generality. Just pass the test.
REFACTOR: Clean up only after green. Remove duplication, improve names, extract helpers. Keep tests green.
- Refactor code, not tests (unless the test itself was poorly written).
- Run tests after every refactor step to catch mistakes early.
Repeat for the next behavior.
Delete Rule
If production code was written before a test, delete it. Do not "adapt" it while writing tests afterward. Delete means delete.
Unverified code is not a time-saving shortcut; it is technical debt. Keeping it forces you to reverse-engineer what it was supposed to do, which takes longer than rewriting it test-first.
Outputs
- Failing test written first (red).
- Minimal implementation that makes it pass (green).
- Refactor that improves the code while keeping tests green.
- Evidence of the TDD cycle (test output before/after).
Guardrails
- One test at a time. Write one test, watch it fail, make it pass. Do not write all tests upfront.
- Test one thing per test. If a test asserts multiple behaviors, split it. Multiple assertions on the same object or outcome are OK; multiple independent behaviors are not.
- Delete unverified code. If you wrote production code before a test, delete it. Rewrite it test-first.
- Watch every failure. Confirm each test fails before you write code. A test that passes on the first run is not testing anything.
- Minimal code. Write only enough production code to pass the test. Save elegance and performance for the REFACTOR phase.
- Keep tests green. Refactor code, but never leave tests failing. A refactor that breaks tests is not done.
Common rationalisations and reality
| Rationalisation |
Reality |
| "Too simple to test" |
Simple code breaks. A test takes 30 seconds to write. |
| "I'll write tests after" |
Tests-after answer "what does this do?" Tests-first answer "what should this do?" — Different questions, different results. |
| "Already manually tested" |
Manual testing is ad-hoc and unmemoried. No record, can't re-run. Automated tests are proof and documentation. |
| "Deleting X hours of work is wasteful" |
Sunk cost. Keeping unverified code is debt that compounds. Rewriting it test-first clears the debt. |
| "TDD will slow me down" |
TDD is faster than debugging. A failing test is a precise bug report; console.log is archaeology. |
| "Mocking everything makes tests too complex" |
Mock only external dependencies (databases, APIs, files). Test logic with real data structures. |
| "This code is too coupled to test" |
That is the signal to refactor. Testability is a design metric. Hard-to-test code is brittle. |
Verification Checklist
Before marking work complete:
Validation
- Run the full test suite for the modified module or package.
- Confirm all tests pass and cover the new behavior.
- Check test coverage (if the repo tracks it) to confirm the new code is exercised.
- Review the test names to ensure they document the expected behavior.
- Smoke test:
- should trigger: "Fix this parser bug by writing a failing test first."
- should not trigger: "Rerun the parser tests before claiming the bug is fixed." (→
verification-before-completion)
Examples
Adding a new validator:
Write a failing test: expect(validateEmail('')).toBe(false) → implement validateEmail() until it passes → add edge-case tests for malformed inputs.
Reproducing a bug before fixing it:
Write expect(parseAmount('£1,000.00')).toBe(1000) → confirm it fails → fix parseAmount() → confirm it passes.
Pinning behavior before refactoring:
Capture current return values in a test suite → refactor the implementation → verify all tests still pass.
See references/tdd-scenarios.md for full TypeScript-focused walkthroughs.
Reference files
references/tdd-scenarios.md — Scenario walkthroughs with TypeScript code examples (500–800 words).
1---2name: test-driven-development3description: "Use when the user explicitly asks for test-driven development (TDD), a red-green-refactor cycle, or test-first implementation — not for general feature work, bug fixes, or refactoring unless TDD discipline is specifically requested."4license: GNU GPL v35metadata:6 source: https://skillmd.com/skills/matt-riley/test-driven-development7 version: 1.1.1 # x-release-please-version8 category: workflow9 audience: general-coding-agent10 maturity: draft11 kind: task12---1314# Test-Driven Development1516Use this skill when implementing any feature, bugfix, or behavior change that requires confidence that the code works as intended. TDD is the practice of writing a failing test first, then writing minimal production code to pass it, then refactoring.1718## Use this skill when1920- Implementing any new feature or functionality.21- Fixing a bug or addressing a regression.22- Refactoring or improving existing code.23- Adding edge-case handling or boundary-condition logic.24- You need to ensure code behavior is correct and documented through executable tests.2526## Do not use this skill when2728- The task is documentation-only or configuration-only with no executable logic.29- The request is exploratory research or one-off investigation without production code output.30- The repository explicitly prohibits or does not support automated testing (rare; ask first).3132## Iron Law3334> **NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST**35>36> Write the test. Watch it fail. Write minimal code to pass. Never write production code without a failing test first.37>38> Tests are specifications. They answer "what should this code do?" Tests written after are archaeology; they can only answer "what does this code do?"3940## Routing boundary4142| Scenario | Use TDD Skill | Route Away |43|---|---|---|44| **New feature request** | Yes — write test for the desired behavior first | N/A |45| **Bug report** | Yes — write test that reproduces the bug, then fix | Consider [github-actions-failure-triage](../github-actions-failure-triage/SKILL.md) if it's a CI failure |46| **Refactor request** | Yes — write test for current behavior, refactor while keeping tests green | Consider [typescript-any-eliminator](../typescript-any-eliminator/SKILL.md) or other targeted hardening skills for narrower improvements |47| **Code review feedback** | Yes if feedback requests behavior change or new handling | Use [review-comment-resolution](../review-comment-resolution/SKILL.md) for process; route back to TDD for code changes |48| **Performance optimization** | Yes — write benchmark test first, then optimize, keep tests green | N/A |49| **Configuration or docs only** | No | Document without this skill |5051## Inputs to gather5253Before starting, clarify:54551. **What is the expected behavior?** (What should the code do?)562. **What test framework is in use?** (Jest, Mocha, Vitest, Go testing, etc. — check repo defaults)573. **What is the scope?** (One function? A whole module? Incremental delivery?)584. **Are there existing tests** that establish patterns or conventions?595. **What are the acceptance criteria?** (Happy path? Edge cases? Error handling?)6061## First move62631. **Do not write production code yet.**642. Write one minimal failing test that asserts the desired behavior.653. Run the test and confirm it fails **for the right reason** (e.g., "function does not exist" or "returned undefined", not a syntax error).664. Only then move to the RED-GREEN-REFACTOR cycle.6768The test failure is your proof that the feature does not exist yet. This is the RED phase.6970## Workflow71721. **RED:** Write one minimal failing test for the specific behavior. Confirm it fails for the right reason (feature missing, not syntax error).73 - One assertion or one logical outcome per test when possible.74 - Use a test name that says what you expect: `should return 42 when input is valid` not `should work`.75 762. **GREEN:** Write the simplest code that makes the test pass. No extra features, no YAGNI (You Aren't Gonna Need It).77 - Minimal. If the test wants a function that returns 42, return 42 (not dynamic logic yet).78 - Ignore performance, elegance, generality. Just pass the test.79 803. **REFACTOR:** Clean up only after green. Remove duplication, improve names, extract helpers. Keep tests green.81 - Refactor code, not tests (unless the test itself was poorly written).82 - Run tests after every refactor step to catch mistakes early.83 844. **Repeat** for the next behavior.8586## Delete Rule8788If production code was written before a test, **delete it**. Do not "adapt" it while writing tests afterward. Delete means delete.8990Unverified code is not a time-saving shortcut; it is technical debt. Keeping it forces you to reverse-engineer what it was supposed to do, which takes longer than rewriting it test-first.9192## Outputs9394- Failing test written first (red).95- Minimal implementation that makes it pass (green).96- Refactor that improves the code while keeping tests green.97- Evidence of the TDD cycle (test output before/after).9899## Guardrails100101- **One test at a time.** Write one test, watch it fail, make it pass. Do not write all tests upfront.102- **Test one thing per test.** If a test asserts multiple behaviors, split it. Multiple assertions on the same object or outcome are OK; multiple independent behaviors are not.103- **Delete unverified code.** If you wrote production code before a test, delete it. Rewrite it test-first.104- **Watch every failure.** Confirm each test fails before you write code. A test that passes on the first run is not testing anything.105- **Minimal code.** Write only enough production code to pass the test. Save elegance and performance for the REFACTOR phase.106- **Keep tests green.** Refactor code, but never leave tests failing. A refactor that breaks tests is not done.107108## Common rationalisations and reality109110| Rationalisation | Reality |111|---|---|112| "Too simple to test" | Simple code breaks. A test takes 30 seconds to write. |113| "I'll write tests after" | Tests-after answer "what does this do?" Tests-first answer "what should this do?" — Different questions, different results. |114| "Already manually tested" | Manual testing is ad-hoc and unmemoried. No record, can't re-run. Automated tests are proof and documentation. |115| "Deleting X hours of work is wasteful" | Sunk cost. Keeping unverified code is debt that compounds. Rewriting it test-first clears the debt. |116| "TDD will slow me down" | TDD is faster than debugging. A failing test is a precise bug report; `console.log` is archaeology. |117| "Mocking everything makes tests too complex" | Mock only external dependencies (databases, APIs, files). Test logic with real data structures. |118| "This code is too coupled to test" | That is the signal to refactor. Testability is a design metric. Hard-to-test code is brittle. |119120## Verification Checklist121122Before marking work complete:123124- [ ] Every new function, method, or behavior has a test.125- [ ] Watched each test fail before implementing the code.126- [ ] Each test failed for the expected reason (not a syntax error or import issue).127- [ ] Wrote minimal code to pass each test; no extra features.128- [ ] All tests pass; no skipped or pending tests.129- [ ] No errors or warnings in test output.130- [ ] Refactored only after all tests passed.131- [ ] Tests are clear and maintainable (good names, obvious assertions).132133## Validation1341351. Run the full test suite for the modified module or package.1362. Confirm all tests pass and cover the new behavior.1373. Check test coverage (if the repo tracks it) to confirm the new code is exercised.1384. Review the test names to ensure they document the expected behavior.139140- Smoke test:141 - should trigger: "Fix this parser bug by writing a failing test first."142 - should not trigger: "Rerun the parser tests before claiming the bug is fixed." (→ `verification-before-completion`)143144## Examples145146- **Adding a new validator:**147 Write a failing test: `expect(validateEmail('')).toBe(false)` → implement `validateEmail()` until it passes → add edge-case tests for malformed inputs.148149- **Reproducing a bug before fixing it:**150 Write `expect(parseAmount('£1,000.00')).toBe(1000)` → confirm it fails → fix `parseAmount()` → confirm it passes.151152- **Pinning behavior before refactoring:**153 Capture current return values in a test suite → refactor the implementation → verify all tests still pass.154155See [`references/tdd-scenarios.md`](references/tdd-scenarios.md) for full TypeScript-focused walkthroughs.156157## Reference files158159- [`references/tdd-scenarios.md`](references/tdd-scenarios.md) — Scenario walkthroughs with TypeScript code examples (500–800 words).