Fix errors · How to use a skill

test-first-with-tdd

Test-driven development in plain steps - write one small failing test, watch it fail for the right reason, write the least code to pass, then tidy up while staying green. Use when adding a feature, fixing a bug, refactoring, or when the user asks for TDD, red-green-refactor or tests first.

Version 1.0 · Updated 2026-10-31

View raw SKILL.md

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/test-first-with-tdd/raw' -o ~/'.claude/skills/test-first-with-tdd/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/test-first-with-tdd/files/LICENSE.txt' -o ~/'.claude/skills/test-first-with-tdd/LICENSE.txt'

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/test-first-with-tdd/raw' -o '.cursor/skills/test-first-with-tdd/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/test-first-with-tdd/files/LICENSE.txt' -o '.cursor/skills/test-first-with-tdd/LICENSE.txt'

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/test-first-with-tdd/raw' -o '.agents/skills/test-first-with-tdd/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/test-first-with-tdd/files/LICENSE.txt' -o '.agents/skills/test-first-with-tdd/LICENSE.txt'

{
  "mcpServers": {
    "theskillvault": {
      "url": "https://theskillvault.ai/mcp"
    }
  }
}

Test first with TDD

Write the test first and watch it fail. Then write just enough code to make it pass. If you never saw the test fail, you do not know it tests the right thing.

When to use

• Adding a new feature or changing behaviour.
• Fixing a bug: first write a test that shows the bug.
• Refactoring code you are afraid to break.

Skip it only for throwaway prototypes, generated code and config files, and say so out loud.

Steps

1. Red: write one small test. Test one behaviour with a clear name, such as "retries a failed request 3 times". Use real code, and avoid mocks unless you cannot.
2. Watch it fail. Run only that test (for example npm test -- retry). It must fail because the feature is missing, not because of a typo or a missing import.
3. Green: write the least code that passes. No extra options or "while I'm here" features.
4. Watch it pass. Run the test again, then the whole suite. Everything must be green.
5. Refactor. Remove duplication and improve names. Run the tests after each change so they stay green.
6. Repeat. Pick the next behaviour and go back to step 1.
7. Wrote code first by accident? Put it aside, write the test, watch it fail, then rebuild the code from the test.

Good test, bad test

• Good: "rejects an empty email" checks the real function and one outcome.
• Bad: "works" checks only that a mock was called three times.

Gotchas

• A test that passes straight away proves nothing. Check that it can fail.
• Keep tests away from real services. Use test keys or a local database, never production secrets or customer data.
• Do not commit .env files or tokens to make a test pass.

Works with any stack

This works with any test runner: Vitest, Jest, node:test, pytest, Go test or others. Use the run command for your project instead of the example.

Done when

• Each new behaviour has a test that you saw fail first.
• The full test suite passes.
• The code has nothing that no test asked for.

Example prompt

"Add a discount code feature, but do it test-first."

---

Adapted from "test-driven-development" in obra/superpowers by Jesse Vincent (MIT). See LICENSE.txt.

Adapted from Jesse Vincent (obra/superpowers) (Copyright (c) 2025 Jesse Vincent), MIT License. Adapted by TheSkillVault: condensed to the core red-green-refactor loop, plain language, stack-neutral examples, added safety and done-when sections.

Licence: MIT License. Attribution when you reuse it: Based on work by Jesse Vincent (obra/superpowers) (Copyright (c) 2025 Jesse Vincent, MIT License), https://github.com/obra/superpowers/blob/2ce8aa15d05bd57213e6f746f953aafb7ded7a8b/skills/test-driven-development/SKILL.md; adapted by TheSkillVault, https://theskillvault.ai