name: tdd
description: Test-Driven Development workflow. Use for ALL code changes - features, bug fixes, refactoring. TDD is non-negotiable.

Test-Driven Development

TDD is the fundamental practice. Every line of production code must be written in response to a failing test.

For how to write good tests, load the testing skill. This skill focuses on the TDD workflow/process.

RED-GREEN-REFACTOR Cycle

RED: Write Failing Test First

• NO production code until you have a failing test
• Test describes desired behavior, not implementation
• Test should fail for the right reason

GREEN: Minimum Code to Pass

• Write ONLY enough code to make the test pass
• Resist adding functionality not demanded by a test
• Commit immediately after green

REFACTOR: Assess Improvements

• Assess AFTER every green (but only refactor if it adds value)
• Commit before refactoring
• All tests must pass after refactoring

TDD Evidence in Commit History

Default Expectation

Commit history should show clear RED → GREEN → REFACTOR progression.

Ideal progression:

commit abc123: test: add failing test for user authentication
commit def456: feat: implement user authentication to pass test
commit ghi789: refactor: extract validation logic for clarity

Rare Exceptions

TDD evidence may not be linearly visible in commits in these cases:

1. Multi-Session Work
- Feature spans multiple development sessions
- Work done with TDD in each session
- Commits organized for PR clarity rather than strict TDD phases
- Evidence: Tests exist, all passing, implementation matches test requirements

2. Context Continuation
- Resuming from previous work
- Original RED phase done in previous session/commit
- Current work continues from that point
- Evidence: Reference to RED commit in PR description

3. Refactoring Commits
- Large refactors after GREEN
- Multiple small refactors combined into single commit
- All tests remained green throughout
- Evidence: Commit message notes "refactor only, no behavior change"

Documenting Exceptions in PRs

When exception applies, document in PR description:

## TDD Evidence

RED phase: commit c925187 (added failing tests for shopping cart)
GREEN phase: commits 5e0055b, 9a246d0 (implementation + bug fixes)
REFACTOR: commit 11dbd1a (test isolation improvements)

Test Evidence:
✅ 4/4 tests passing (7.7s with 4 workers)

Important: Exception is for EVIDENCE presentation, not TDD practice. TDD process must still be followed - these are cases where commit history doesn't perfectly reflect the process that was actually followed.

Coverage Verification - CRITICAL

NEVER Trust Coverage Claims Without Verification

Always run coverage yourself before approving PRs.

Verification Process

Before approving any PR claiming "100% coverage":

1. Check out the branch
   bash git checkout feature-branch

2. Run coverage verification:
   bash cd packages/core pnpm test:coverage # OR pnpm exec vitest run --coverage

3. Verify ALL metrics hit 100%:

4. Lines: 100% ✅
5. Statements: 100% ✅
6. Branches: 100% ✅

7. Functions: 100% ✅

8. Check that tests are behavior-driven (not testing implementation details)

For anti-patterns that create fake coverage (coverage theater), see the testing skill.

Reading Coverage Output

Look for the "All files" line in coverage summary:

File           | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
---------------|---------|----------|---------|---------|-------------------
All files      |     100 |      100 |     100 |     100 |
setup.ts       |     100 |      100 |     100 |     100 |
context.ts     |     100 |      100 |     100 |     100 |
endpoints.ts   |     100 |      100 |     100 |     100 |

✅ This is 100% coverage - all four metrics at 100%.

Red Flags

Watch for these signs of incomplete coverage:

❌ PR claims "100% coverage" but you haven't verified
- Never trust claims without running coverage yourself

❌ Coverage summary shows <100% on any metric

All files      |   97.11 |    93.97 |   81.81 |   97.11 |

• This is NOT 100% coverage (Functions: 81.81%, Lines: 97.11%)

❌ "Uncovered Line #s" column shows line numbers

setup.ts       |   95.23 |      100 |      60 |   95.23 | 45-48, 52-55

• Lines 45-48 and 52-55 are not covered

❌ Coverage gaps without explicit exception documentation
- If coverage <100%, exception should be documented (see Exception Process below)

When Coverage Drops, Ask

"What business behavior am I not testing?"

NOT "What line am I missing?"

Add tests for behavior, and coverage follows naturally.

100% Coverage Exception Process

Default Rule: 100% Coverage Required

No exceptions without explicit approval and documentation.

Acceptable Exceptions (No Approval Needed)

Re-export Files: Files that only re-export from other modules don't need coverage.

// index.ts - re-export only, no implementation
export { createSupabaseClient } from './supabase/client';

Why: Re-exports don't implement behavior - they're organizational. The actual implementation files should have 100% coverage.

Verification: When checking coverage, verify that implementation files (not re-exports) have 100% coverage.

Example Coverage Output:

All files     |   96.15 |    83.33 |   66.66 |   96.15 |
 src          |       0 |        0 |       0 |       0 |
  index.ts    |       0 |        0 |       0 |       0 | 1  ← Re-export, acceptable
 src/supabase |     100 |      100 |     100 |     100 |
  client.ts   |     100 |      100 |     100 |     100 |  ← Implementation, 100% ✅

Requesting an Exception

If 100% coverage cannot be achieved:

Step 1: Document in package README

Explain:
- Current coverage metrics
- WHY 100% cannot be achieved in this package
- WHERE the missing coverage will come from (integration tests, E2E, etc.)

Step 2: Get explicit approval

From project maintainer or team lead

Step 3: Document in CLAUDE.md

Under "Test Coverage: 100% Required" section, list the exception

Example Exception:

## Current Exceptions

- **Next.js Adapter**: 86% function coverage
  - Documented in `/packages/nextjs-adapter/README.md`
  - Missing coverage from SSR functions (tested in E2E layer)
  - Approved: 2024-11-15

Remember

The burden of proof is on the requester. 100% is the default expectation.

Development Workflow

Adding a New Feature

1. Write failing test - describe expected behavior
2. Run test - confirm it fails (pnpm test:watch)
3. Implement minimum - just enough to pass
4. Run test - confirm it passes
5. Refactor if valuable - improve code structure
6. Commit - with conventional commit message

Workflow Example

# 1. Write failing test
it('should reject empty user names', () => {
  const result = createUser({ id: 'user-123', name: '' });
  expect(result.success).toBe(false);
}); # ❌ Test fails (no implementation)

# 2. Implement minimum code
if (user.name === '') {
  return { success: false, error: 'Name required' };
} # ✅ Test passes

# 3. Refactor if needed (extract validation, improve naming)

# 4. Commit
git add .
git commit -m "feat: reject empty user names"

Commit Messages

Use conventional commits format:

feat: add user role-based permissions
fix: correct email validation regex
refactor: extract user validation logic
test: add edge cases for permission checks
docs: update architecture documentation

Format:
- feat: - New feature
- fix: - Bug fix
- refactor: - Code change that neither fixes bug nor adds feature
- test: - Adding or updating tests
- docs: - Documentation changes

Pull Request Requirements

Before submitting PR:

• [ ] All tests must pass
• [ ] All linting and type checks must pass
• [ ] Coverage verification REQUIRED - claims must be verified before review/approval
• [ ] PRs focused on single feature or fix
• [ ] Include behavior description (not implementation details)

Example PR Description:

## Summary

Adds support for user role-based permissions with configurable access levels.

## Behavior Changes

- Users can now have multiple roles with fine-grained permissions
- Permission check via `hasPermission(user, resource, action)`
- Default role assigned if not specified

## Test Evidence

✅ 42/42 tests passing
✅ 100% coverage verified (see coverage report)

## TDD Evidence

RED: commit 4a3b2c1 (failing tests for permission system)
GREEN: commit 5d4e3f2 (implementation)
REFACTOR: commit 6e5f4a3 (extract permission resolution logic)

Refactoring Priority

After green, classify any issues:

For detailed refactoring methodology, load the refactoring skill.

Anti-Patterns to Avoid

• ❌ Writing production code without failing test
• ❌ Testing implementation details (spies on internal methods)
• ❌ 1:1 mapping between test files and implementation files
• ❌ Using let/beforeEach for test data
• ❌ Trusting coverage claims without verification
• ❌ Mocking the function being tested
• ❌ Redefining schemas in test files
• ❌ Factories returning partial/incomplete objects
• ❌ Speculative code ("just in case" logic without tests)

For detailed testing anti-patterns, load the testing skill.

Summary Checklist

Before marking work complete:

• [ ] Every production code line has a failing test that demanded it
• [ ] Commit history shows TDD evidence (or documented exception)
• [ ] All tests pass
• [ ] Coverage verified at 100% (or exception documented)
• [ ] Test factories used (no let/beforeEach)
• [ ] Tests verify behavior (not implementation details)
• [ ] Refactoring assessed and applied if valuable
• [ ] Conventional commit messages used