tdd · diff
git:20260523.36e5a7e to git:20260711.4f85074
18 added, 75 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: tdd
- description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
+ description: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
---
# Test-Driven Development
- ## Philosophy
-
- **Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
-
- **Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
-
- **Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
-
- See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
-
- ## Anti-Pattern: Horizontal Slices
-
- **DO NOT write all tests first, then all implementation.** That's horizontal slicing: RED becomes "write all tests," GREEN becomes "write all code." It produces tests of _imagined_ behavior coupled to assumed shapes; they pass when behavior breaks and fail when behavior is fine.
-
- **Correct approach**: vertical slices (tracer bullets). One test → one implementation → repeat. Each cycle responds to what you learned from the previous one.
-
- - WRONG (horizontal): `RED: test1..testN`, then `GREEN: impl1..implN`
- - RIGHT (vertical): `RED→GREEN: test1→impl1`, then `test2→impl2`, ...
-
- ## Workflow
-
- ### 1. Planning
-
- When exploring the codebase, use the project's domain glossary so that test names and interface vocabulary match the project's language, and respect ADRs in the area you're touching.
-
- Before writing any code:
-
- - [ ] Confirm with user what interface changes are needed
- - [ ] Confirm with user which behaviors to test (prioritize)
- - [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
- - [ ] Design interfaces for [testability](interface-design.md)
- - [ ] List the behaviors to test (not implementation steps)
- - [ ] Get user approval on the plan
-
- Ask: "What should the public interface look like? Which behaviors are most important to test?"
-
- **You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case.
-
- ### 2. Tracer Bullet
-
- Write ONE test that confirms ONE thing about the system:
-
- ```
- RED: Write test for first behavior → test fails
- GREEN: Write minimal code to pass → test passes
- ```
+ TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle — consult them before and during the loop, not after.
- This is your tracer bullet - proves the path works end-to-end.
+ When exploring the codebase, use the project's domain glossary (the Glossary in `docs/README.md`) so test names and interface vocabulary match the project's language, and respect ADRs in the area you're touching.
- ### 3. Incremental Loop
+ ## What a good test is
- For each remaining behavior:
+ Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification — "user can checkout with valid cart" tells you exactly what capability exists — and survives refactors because it doesn't care about internal structure.
- ```
- RED: Write next test → fails
- GREEN: Minimal code to pass → passes
- ```
+ See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines. For module shape — small interfaces hiding deep implementations, and where seams belong — run the `/codebase-design` skill.
- Rules:
+ ## Seams — where tests go
- - One test at a time
- - Only enough code to pass current test
- - Don't anticipate future tests
- - Keep tests focused on observable behavior
+ A **seam** is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.
- ### 4. Refactor
+ **Test only at pre-agreed seams.** Before writing any test, write down the seams under test and confirm them with the user. No test is written at an unconfirmed seam. You can't test everything — agreeing the seams up front is how testing effort lands on the critical paths and complex logic instead of every edge case.
- After all tests pass, look for [refactor candidates](refactoring.md):
+ Ask: "What's the public interface, and which seams should we test?"
- - [ ] Extract duplication
- - [ ] Deepen modules (move complexity behind simple interfaces)
- - [ ] Apply SOLID principles where natural
- - [ ] Consider what new code reveals about existing code
- - [ ] Run tests after each refactor step
+ ## Anti-patterns
- **Never refactor while RED.** Get to GREEN first.
+ - **Implementation-coupled** — mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior hasn't changed.
+ - **Tautological** — the assertion recomputes the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), so it passes by construction and can never disagree with the code. Expected values must come from an independent source of truth — a known-good literal, a worked example, the spec.
+ - **Horizontal slicing** — writing all tests first, then all implementation. Bulk tests verify _imagined_ behavior: you test the _shape_ of things rather than user-facing behavior, the tests go insensitive to real changes, and you commit to test structure before understanding the implementation. Work in **vertical slices** instead — one test → one implementation → repeat, each test a **tracer bullet** that responds to what the last cycle taught you.
- ## Checklist Per Cycle
+ ## Rules of the loop
- ```
- [ ] Test describes behavior, not implementation
- [ ] Test uses public interface only
- [ ] Test would survive internal refactor
- [ ] Code is minimal for this test
- [ ] No speculative features added
- ```
+ - **Red before green.** Write the failing test first, then only enough code to pass it. Don't anticipate future tests or add speculative features.
+ - **One slice at a time.** One seam, one test, one minimal implementation per cycle.
+ - **Refactoring is not part of the loop.** It belongs to the review stage — `/simplify`, `/code-review`, and this repo's PR review pipeline (`/pr-ci-review`) — not the red → green implementation cycle.