Test-Driven Development (TDD) Skill

Strict Red-Green-Refactor workflow enforcement with automated validation.

This skill acts as a TDD workflow state machine that enforces discipline through validators. It prevents common TDD anti-patterns and ensures proper test-first development.

Quick Start

# Start TDD for a new feature
/sc:tdd "add user password validation"

# TDD with specific framework
/sc:tdd payment-module --framework pytest

# Fast mode (skip full suite after green, run at end)
/sc:tdd api-endpoint --fast

# Allow snapshot tests
/sc:tdd ui-component --allow-snapshots

Behavioral Flow

This skill enforces a 7-step Red-Green-Refactor cycle:

1. Initialize - Detect scope, framework, create state
2. RED: Write Failing Test - Create test for missing functionality
3. RED: Validate Failure - Run validator, confirm SEMANTIC failure (assertion, not compile error)
4. GREEN: Implement Minimally - Write smallest code to pass test
5. GREEN: Validate Passing - Run validators, confirm test passes + no regressions
6. REFACTOR: Improve Design - Clean up with tests as safety net
7. REFACTOR: Validate Stability - Re-run suite, confirm still green

State Machine

IDLE → RED_PENDING → RED_CONFIRMED → GREEN_PENDING →
GREEN_CONFIRMED → REFACTOR_PENDING → REFACTOR_COMPLETE → [cycle repeats]

Critical Rules:

• Validator output is source of truth - If validator says blocked, you MUST stop
• Exit codes matter: 0 = allowed, 2 = blocked, 3 = error (ask user for help)
• No bypassing - Every phase transition requires validator approval

Phase 1: Initialize (IDLE → RED_PENDING)

When: User requests TDD workflow

Your Actions:

1. Detect scope root:

python .claude/skills/sc-tdd/scripts/framework_detector.py \
  --detect-scope $(pwd) \
  --json

2. Initialize state:

python .claude/skills/sc-tdd/scripts/tdd_state_machine.py \
  --scope-root <detected_scope> \
  --init \
  --json

3. Transition to RED_PENDING:

python .claude/skills/sc-tdd/scripts/tdd_state_machine.py \
  --scope-root <scope> \
  --phase RED_PENDING \
  --evidence "User requested: <feature_description>" \
  --json

Output: Confirm initialization, explain RED phase rules to user

Phase 2: Write Failing Test (RED_PENDING)

Rules:

• User writes test first
• You MAY help write the test
• You MAY add empty stubs/interfaces to make test compile (e.g., pass, raise NotImplementedError, empty functions)
• You MUST NOT write production implementation yet

Your Actions:

1. Help user write test file
2. Explain test must fail with assertion (not compile error)
3. When test is written, proceed to validation

Phase 3: Validate Red (RED_PENDING → RED_CONFIRMED)

CRITICAL: You MUST run this validator before proceeding.

Command:

python .claude/skills/sc-tdd/scripts/validate_red.py \
  --scope-root <scope> \
  --json

Interpretation:

• Exit code 0 + "allowed": true → Proceed to RED_CONFIRMED
• Exit code 2 + "allowed": false → STOP, show user reasons, ask them to fix

Common Blocking Reasons:

• "Test failed but NOT with semantic assertion" - Compile error, need to fix test
• "Test PASSED (expected failure)" - Test not actually testing the feature
• "No changed test files found" - Forgot to write test

If Blocked: Show user the reasons array, artifacts.test_output, and ask them to address the issue. DO NOT propose production code until validator allows.

If Allowed: Store artifacts.intent_test information, transition state, proceed to GREEN phase.

Phase 4: Implement Minimally (RED_CONFIRMED → GREEN_PENDING)

Rules:

• Write MINIMAL implementation to pass the test
• Focus on making test pass, not perfection
• NO premature optimization
• NO extra features beyond test requirements

Your Actions:

1. Confirm current state is RED_CONFIRMED
2. Implement minimal production code
3. Explain your implementation approach
4. Transition to GREEN_PENDING:

python .claude/skills/sc-tdd/scripts/tdd_state_machine.py \
  --scope-root <scope> \
  --phase GREEN_PENDING \
  --evidence "Implemented: <description>" \
  --json

5. Proceed to validation

Phase 5: Validate Green (GREEN_PENDING → GREEN_CONFIRMED)

CRITICAL: You MUST run this validator before claiming success.

Command (standard):

python .claude/skills/sc-tdd/scripts/validate_green.py \
  --scope-root <scope> \
  --json

Command (fast mode, skips full suite):

python .claude/skills/sc-tdd/scripts/validate_green.py \
  --scope-root <scope> \
  --skip-full-suite \
  --json

Interpretation:

• Exit code 0 + "allowed": true → GREEN_CONFIRMED, proceed to refactor
• Exit code 2 + "allowed": false → STOP, implementation insufficient

Common Blocking Reasons:

• "Intent test still FAILING" - Implementation didn't make test pass
• "Full test suite FAILED - REGRESSION DETECTED" - Broke existing tests

If Blocked: Show user the failure details, fix implementation, re-validate.

If Allowed: Celebrate! Test passes, no regressions. Ask user if they want to refactor or complete cycle.

Phase 6: Refactor (Optional, GREEN_CONFIRMED → REFACTOR_PENDING)

Rules:

• Improve code quality WITHOUT changing behavior
• Tests must continue passing
• Allowed changes: extract methods, rename variables, improve clarity, remove duplication
• NOT allowed: add features, change test expectations, weaken tests

Your Actions:

1. Ask user if they want to refactor
2. If yes, transition to REFACTOR_PENDING
3. Propose refactorings
4. Apply changes
5. Re-run tests to confirm stability

Phase 7: Validate Refactor (REFACTOR_PENDING → REFACTOR_COMPLETE)

Command:

python .claude/skills/sc-tdd/scripts/validate_green.py \
  --scope-root <scope> \
  --json

(Same validator, ensures tests still pass)

If Allowed: Cycle complete! Ask user:

• Continue with next test? (start new RED cycle)
• Feature complete?

Flags

Flag	Type	Default	Description
--framework	string	auto	Test framework: auto, pytest, jest, vitest, go, cargo
--fast	bool	false	Skip full suite in GREEN, run only at feature completion
--allow-snapshots	bool	false	Allow snapshot tests as semantic failures
--strict	bool	false	No stubs allowed in RED (must be pure test-first)

Personas Activated

• agent-test-automator - Test design expertise
• agent-quality-engineer - Test quality validation
• agent-python-pro / agent-typescript-expert - Language-specific implementation
• agent-backend-architect / agent-frontend-architect - Architecture guidance

MCP Integration

• PAL MCP
  • mcp__pal__codereview - Review test quality and implementation
  • mcp__pal__debug - Investigate unexpected test failures

Anti-Patterns Detected & Blocked

Blocked by validators:

• Production code before failing test
• Compile errors counted as "red" (must be runtime assertion)
• Test passing when it should fail
• Weakened assertions during GREEN phase
• Regressions in full suite

Warned by validators:

• Snapshot tests (blocked unless --allow-snapshots)
• Flaky patterns: sleep, network, random without mocking
• Assertionless tests
• Tests that always pass

Tool Coordination

• Read - Read existing test files, implementation code, framework configs
• Write - Create new test files, state files
• Edit - Modify tests and implementation incrementally
• Bash - Execute validator scripts (NON-NEGOTIABLE, always run validators)
• Glob - Find test files, manifest files, CI configs
• Grep - Search for test patterns, framework usage

Quality Dimensions

Evaluated on:

• Correctness (30%) - Tests pass, implementation works as specified
• Completeness (20%) - All test scenarios covered, edge cases handled
• Testability (20%) - Tests are clear, maintainable, fast, deterministic
• Maintainability (15%) - Code is clean, well-structured, no duplication
• Discipline (15%) - Followed TDD process, no shortcuts, proper Red-Green-Refactor

Threshold: 70+ score required to mark feature complete

Examples

Example 1: Feature Development

/sc:tdd "add password validation: minimum 8 characters"

# Workflow enforced:
# 1. Initialize state for current directory scope
# 2. User/Claude writes test_password_validation.py:
#    def test_password_min_length():
#        assert validate_password("short") == False
#        assert validate_password("longenough") == True
# 3. Run validate_red.py → confirms test FAILS with AssertionError (no validate_password function)
# 4. Claude implements:
#    def validate_password(password: str) -> bool:
#        return len(password) >= 8
# 5. Run validate_green.py → confirms test PASSES, full suite GREEN
# 6. Ask user about refactoring
# 7. Feature complete or next cycle

Example 2: Bug Fix with TDD

/sc:tdd "fix: user deletion doesn't cascade to posts" --framework pytest

# Workflow:
# 1. Write test exposing bug (test fails showing cascade doesn't work)
# 2. Validate RED (confirms bug exists)
# 3. Fix cascade behavior
# 4. Validate GREEN (confirms bug fixed, no regressions)

Example 3: Monorepo Package

cd backend/user-service
/sc:tdd "add email validation"

# Auto-detects:
# - scope_root: backend/user-service (nearest package.json)
# - framework: jest (from package.json devDependencies)
# - Runs tests only in this package scope

Troubleshooting

"No testing framework detected"

Solution:

1. Check if test framework is installed
2. Specify manually: --framework pytest
3. Ensure framework config exists (pytest.ini, jest.config.js, etc.)

"Test failed but NOT with semantic assertion"

Cause: Compile error, import error, syntax error

Solution:

1. Fix test to compile and run
2. Add empty stub if needed: def my_function(): raise NotImplementedError
3. Re-run validate_red.py

"Full test suite timed out"

Solution:

1. Use --fast mode for faster cycles
2. Run full suite only at feature completion
3. Investigate slow tests

"Multiple test files changed"

Cause: More than one test file modified (TDD requires focus)

Solution:

1. Commit/stash other changes
2. Work on one test at a time
3. Use multiple micro-cycles

State Recovery

If state file is lost or corrupted:

1. Validator will attempt recovery from git diff + current test results
2. You can manually re-initialize: python tdd_state_machine.py --init --scope-root <path>
3. State is per-scope, so multiple packages can have independent TDD states

Important Reminders

1. ALWAYS run validators before phase transitions - This is non-negotiable
2. Trust validator output over assumptions - If validator says blocked, stop
3. Exit codes matter: Check both exit code AND "allowed" field in JSON
4. One test at a time - TDD is about smallest increments
5. Semantic failures only - Compile errors don't count as proper "red"
6. Full suite matters - Don't skip unless using --fast mode explicitly

---

Version: 1.0.0 Last Updated: 2025-01-09 Maintainer: SuperClaude Framework