TDD

Red-Green-Refactor workflow with explicit approval gates. Tests are written, reviewed, and confirmed failing before any implementation. Refactoring only happens after explicit approval.

Recommended model: Sonnet

Phase 1 — RED (write failing tests)

Step 1: Identify test cases with presets

Before writing tests, ask:

What behaviors should these tests cover? Select all that apply:

1. Happy path — valid input returns expected output
2. Invalid input — validation errors caught at boundary
3. Not found — missing resource returns 404/error
4. Auth/permission — unauthorized access rejected
5. Edge cases — empty list, zero values, max limits
6. Other — describe below

Propose additional test cases based on the task. Wait for the user to confirm the list.

Step 2: Write tests only

Write the test file(s). No implementation code. No scaffolding beyond what the test imports need.

• TypeScript: use Vitest (preferred) or Jest; files at *.test.ts
• Go: _test.go files; use table-driven tests

Step 3: Show tests and get approval

Present the tests to the user:

Tests written. Do these cover the right cases? [y / add more / remove N / edit N]

Iterate until the user approves. Do not proceed until approved.

Step 4: Run tests — must FAIL

Run the tests:

• TypeScript: npx vitest run <test-file> or npx jest <test-file>
• Go: go test ./... -run TestFunctionName

Show the full failure output. If tests pass without implementation, stop:

Warning: Tests passed without implementation — they may not be testing the right thing. Investigate before proceeding.

Step 5: Hard stop

Tests are RED and approved. Proceed to implementation? [y / n]

Wait for explicit y.

Phase 2 — GREEN (minimal implementation)

Step 6: Write minimal implementation

Write only enough code to make the tests pass:

• No premature abstractions
• No extra error handling for scenarios not covered by tests
• No features beyond what the tests assert

Step 7: Run tests — must PASS

Run the full test suite. Show pass output.

If any test fails: fix implementation (not tests) until all pass.

Step 8: Hard stop

Tests are GREEN. Refactor now? [y / skip refactor]

If user skips: jump to commit phase. If y: continue to Phase 3.

Phase 3 — REFACTOR (only after approval)

Step 9: Present refactor plan

Show what will change and why:

Refactor plan:
  - Extract shared validation logic to users.schema.ts (DRY — duplicated in 2 places)
  - Rename `processUser` → `mapUserToResponse` (clarity)
  - No behavior changes — all tests must still pass

Proceed with refactor? [y / n / modify]

Wait for approval.

Step 10: Apply refactor and re-verify

Apply changes. Run tests again — they must still pass.

If tests break: fix the refactor, not the tests.

Step 11: Commit

Suggest committing via /commit after the green or refactor phase.

Rules

• Never write implementation before tests are RED and user-approved
• Never skip the failure verification step — if you didn't watch the test fail, you don't know it tests the right thing
• Never refactor before the user approves the refactor plan
• Fix implementation to pass tests — never weaken tests to pass implementation
• Mock at boundaries only (external APIs, DB) — never mock implementation internals

TypeScript Test Conventions

import { describe, it, expect, vi } from 'vitest'

describe('createUser', () => {
  it('returns created user on valid input', async () => { ... })
  it('throws ValidationError on invalid email', async () => { ... })
})

Go Test Conventions

func TestCreateUser(t *testing.T) {
    tests := []struct {
        name    string
        input   CreateUserInput
        want    *User
        wantErr error
    }{
        { name: "valid input", input: ..., want: ... },
        { name: "invalid email", input: ..., wantErr: &ValidationError{} },
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) { ... })
    }
}