Skip to content

swell-agents/coding-skills / skills/running-tdd-cycles

running-tdd-cycles

Verified

Drive strict red-green-refactor TDD discipline on any code change, any language.

Loop

For each new piece of behaviour:

1. Extract <requirement> — the smallest piece of logic that adds value.
2. RED      → write ONE failing test that pins down <requirement>.
3. GREEN    → write the minimal code that makes it pass.
4. REFACTOR → improve structure with the test as a safety net.
5. COMMIT   → one logical change per commit (defer to committing-changes).
6. Repeat 2–5 until the task is done.
7. REVIEW   → defer to reviewing-changes for the final pass.

Always one requirement per cycle. If the cycle feels big, the requirement was too big — split it.

RED — write a failing test

  • One test, one requirement. Don't write a test suite up front; one test, fail, pass, refactor, next.
  • Test names are claims, not labels. Verify the fixture shape, input source, and assertion target match the name before the test goes green. A test named test_decodesV4Quote that loads a V5 fixture is silently broken: it passes but pins the wrong invariant, and the regression lands in the wrong place. Common causes: renamed a test and forgot to update the fixture; copy-pasted a fuzzy assertion from a sibling test without re-targeting it.
  • Arrange-Act-Assert. Three blocks, one assertion focus. Use should_X_when_Y naming where the framework allows it.
  • Fail for the right reason. Run the test before writing implementation. The failure message must point at missing behaviour, not at a typo, missing import, or fixture mistake. If it doesn't, the test is wrong.
  • No premature edge cases. Cover the happy path first. Edge cases (null, empty collections, boundary values, concurrent access, errors) get their own RED-GREEN-REFACTOR cycles.
  • Property-based when applicable. Prefer hypothesis (Python), fast-check (JS/TS), or quickcheck (Haskell/Rust) for invariants. Example-based tests are for specific edge cases or documentation. See reference/property-based-testing.md.
  • Reuse strategies. Before writing a generator, check tests/strategies.py (or the project equivalent) for shared fixtures/strategies. Add new ones back to the shared module.

Framework cues

  • Python (pytest) — fixtures with explicit scopes, pytest.mark.parametrize for multiple cases, hypothesis for properties.
  • JS/TS (Vitest/Jest) — vi.fn() / jest.fn() mocks; @testing-library/* for components; fast-check for properties.
  • Go — table-driven tests with subtests via t.Run(name, func(t *testing.T) {...}); t.Parallel() where safe.
  • Ruby (RSpec) — let for lazy fixtures, let! for eager; nested context for branching scenarios.
  • Solidity (Foundry) — forge test -vvv; parametric fuzz tests via function testFoo(uint256 x); bound(x, min, max) not if-guards. See solidity-conventions.

GREEN — minimal code to pass

  • Smallest possible change. Hard-coded returns are fine for the first cycle. Triangulate (generalise) only when a second test forces it.
  • No bonus features. Don't add error handling, logging, optimisation, or generality unless a test demands it. The next cycle will.
  • Don't modify the test. If the test is wrong, go back to RED. If the test is right and the implementation is wrong, fix the implementation.
  • Run the full test suite after each change. Confirm green; confirm no regression.

REFACTOR — improve structure

  • Tests stay green throughout. Run the suite after every micro-step.
  • Code smells to act on: duplication (extract method/class), long methods (decompose), large classes (split SRP), long parameter lists (parameter object), feature envy (move method), primitive obsession (value object), switch statements driven by type (polymorphism), dead code (delete).
  • SOLID weights. Single Responsibility first; the others when they pull their weight. See engineering-philosophy.
  • Tests refactor too. Extract common fixtures, rename for clarity, eliminate test duplication. Coverage stays equal or improves.
  • Performance refactors are measured. Profile before, profile after; commit the measurement alongside the change.
  • Refactoring is not optional. If you skip it, technical debt compounds and the next RED gets harder to write.

Anti-patterns

  • Writing implementation before the test.
  • Writing a test that already passes.
  • Writing many tests at once and implementing them in a batch.
  • Modifying a test to make it pass.
  • Skipping refactor because "the test passed."
  • Adding tests during the GREEN phase.
  • Test-after rationalised as TDD.

If the discipline breaks: stop, identify the violated phase, revert to the last green state, resume from the right phase, note what went wrong.

Validation checkpoints

End of RED: test exists, test fails, failure message names the missing behaviour, no false positive.

End of GREEN: all tests pass, the change is the minimum that could possibly work, the test wasn't modified, coverage didn't drop.

End of REFACTOR: all tests still pass, complexity (cyclomatic, length) at least no worse, duplication addressed, names readable, performance measured if performance was the goal.

Scratch testing

Quick exploration belongs in a gitignored scratch file, not in production code or in the test suite:

  • Python → test.py (see python-conventions and reference/scratch-testing.md).
  • Go → test.go with //go:build scratch tag (see go-conventions).
  • Solidity → script/Scratch.s.sol or chisel REPL (see solidity-conventions).

Never use inline heredocs (uv run python << EOF, go run -, forge script --via-stdin) — the file pattern keeps history and stays inspectable.

Cross-references

  • committing-changes — commit after every successful GREEN or REFACTOR phase.
  • reviewing-changes — final pass after the loop ends.
  • python-conventions / go-conventions / solidity-conventions — language-specific test runner setup.
  • engineering-philosophy — Small Steps, Investigate-Don't-Mask, KISS, YAGNI all apply directly.

Reference

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall