tdd-process

What this skill does

**In Plan Mode: Plans should be test specifications, not implementation designs. Include key insights, architectural constraints, and suggestions—but never the full implementation of production code.**

# 🚨 CRITICAL: TDD STATE MACHINE GOVERNANCE 🚨

**EVERY SINGLE MESSAGE MUST START WITH YOUR CURRENT TDD STATE**

Format:
```
🔴 TDD: RED
🟢 TDD: GREEN
🔵 TDD: REFACTOR
⚪ TDD: PLANNING
🟡 TDD: VERIFY
⚠️ TDD: BLOCKED
```

**NOT JUST THE FIRST MESSAGE. EVERY. SINGLE. MESSAGE.**

When you read a file → prefix with TDD state
When you run tests → prefix with TDD state
When you explain results → prefix with TDD state
When you ask a question → prefix with TDD state

Example:
```
⚪ TDD: PLANNING
Writing test for negative price validation...

⚪ TDD: PLANNING
Running npm test to see it fail...

⚪ TDD: PLANNING
Test output shows: Expected CannotHaveNegativePrice error but received -50
Test fails correctly. Transitioning to RED.

🔴 TDD: RED
Test IS failing. Addressing what the error message demands...
```

**🚨 FAILURE TO ANNOUNCE TDD STATE = SEVERE VIOLATION 🚨**

---

<meta_governance>
  🚨 STRICT STATE MACHINE GOVERNANCE 🚨

  - CANNOT skip states or assume completion without evidence
  - MUST announce state on EVERY message
  - MUST validate post-conditions before transitioning

  **Before each response:** Verify your claimed state matches your tool call evidence.
  If mismatch: `🔥 STATE VIOLATION DETECTED` → announce correct state → recover.

  **State announcement:** Every message starts with `🔴 TDD: RED` (or current state).
  Forgot prefix? Announce violation immediately, then continue.
</meta_governance>

<state_machine>
  <diagram>
```
                  user request
                       ↓
                 ┌──────────┐
            ┌────│ PLANNING │────┐
            │    └─────┬────┘    │
            │          │         │
            │  test fails        │
            │  correctly         │
  unclear   │          ↓         │ blocker
            │    ┌──────────┐    │
            └────│   RED    │    │
                 │          │    │
                 │ Test IS  │    │
                 │ failing  │    │
                 └────┬─────┘    │
                      │          │
              test    │          │
              passes  │          │
                      ↓          │
                 ┌──────────┐    │
                 │  GREEN   │    │
                 │          │    │
                 │ Test IS  │    │
                 │ passing  │    │
                 └────┬─────┘────┘
                      │
          refactoring │
          needed      │
                      ↓
                 ┌──────────┐
            ┌────│ REFACTOR │
            │    │          │
            │    │ Improve  │
            │    │ design   │
            │    └────┬─────┘
            │         │
            │    done │
            │         │
            │         ↓
            │    ┌──────────┐
            │    │  VERIFY  │
            │    │          │
            │    │ Run full │
  fail      │    │ suite +  │
            │    │ lint +   │
            └────│ build    │
                 └────┬─────┘
                      │
                 pass │
                      │
                      ↓
                 [COMPLETE]
```
  </diagram>

  <states>
    <state name="PLANNING">
      <prefix>⚪ TDD: PLANNING</prefix>
      <purpose>Writing a failing test to prove requirement</purpose>

      <pre_conditions>
        ✓ User has provided a task/requirement/bug report
        ✓ No other TDD cycle in progress
      </pre_conditions>

      <actions>
        1. Analyze requirement/bug
        2. Ask clarifying questions if needed
        3. Determine what behavior needs testing
        4. Identify edge cases using writing-tests skill checklists (numbers, strings, collections, dates, null/undefined, typed property validation)
        5. Write test for specific behavior
        6. Run test (use Bash tool to execute test command)
        7. VERIFY test fails correctly
        8. Show exact failure message to user (copy/paste verbatim output)
        9. Justify why failure message proves test is correct
        10. If failure is "method doesn't exist" - implement empty/dummy method and re-run from step 6
        11. Repeat until you get a "meaningful" failure
        12. Improve the code to produce a more explicit error message. Does the test failure provide a precise reason for the failure, if not ask the user if they want to make it better.
        13. Transition to RED
      </actions>

      <post_conditions>
        ✓ Test written and executed
        ✓ Test FAILED correctly (red bar achieved)
        ✓ Failure message shown to user verbatim
        ✓ Failure reason justified (proves test is correct)
        ✓ Failure is "meaningful" (not setup/syntax error)
      </post_conditions>

      <validation_before_transition>
        BEFORE transitioning to RED, announce:
        "Pre-transition validation:
        ✓ Test written: [yes]
        ✓ Test executed: [yes]
        ✓ Test failed correctly: [yes]
        ✓ Failure message shown: [yes - output above]
        ✓ Meaningful failure: [yes - justification]

        Transitioning to RED - test is now failing for the right reason."
      </validation_before_transition>

      <transitions>
        - PLANNING → RED (when test fails correctly - red milestone achieved)
        - PLANNING → BLOCKED (when cannot write valid test)
      </transitions>
    </state>

    <state name="RED">
      <prefix>🔴 TDD: RED</prefix>
      <purpose>Test IS failing for the right reason. Implement ONLY what the error message demands.</purpose>

      🚨 CRITICAL: You are in RED state - test IS CURRENTLY FAILING. You MUST implement code and see test PASS, code COMPILE, code LINT before transitioning to GREEN.
      DO NOT transition to GREEN until you have:
      1. Implemented ONLY what the error message demands
      2. Executed the test with Bash tool
      3. Seen the SUCCESS output (green bar)
      4. Executed compile check and seen SUCCESS
      5. Executed lint check and seen PASS
      6. Shown all success outputs to the user

      <pre_conditions>
        ✓ Test written and executed (from PLANNING)
        ✓ Test IS FAILING correctly (red bar visible)
        ✓ Failure message shown and justified
        ✓ Failure is "meaningful" (not setup/syntax error)
      </pre_conditions>

      <actions>
        1. Read the error message - what does it literally ask for?
        2. 🚨 MANDATORY SELF-CHECK - announce before implementing:
           "Minimal implementation check:
           - Error demands: [what the error literally says]
           - Could hardcoded value work? [yes/no]
           - If yes: [what hardcoded value]
           - If no: [why real logic is required]"

           Guidelines:
           - If test asserts `x === 5` → return `5`
           - If test asserts `count === 0` → return object with `count: 0`
           - If test asserts type → return minimal stub of that type
           - Only add logic when tests FORCE you to (multiple cases, different inputs)
        3. Implement ONLY what that error message demands (hardcoded if possible)
        4. Do NOT anticipate future errors - address THIS error only
        5. Run test (use Bash tool to execute test command)
        6. VERIFY test PASSES (green bar)
        7. Show exact success message to user (copy/paste verbatim output)
        8. Run quick compilation check (e.g., tsc --noEmit, or project-specific compile command)
        9. Run lint on changed code
        10. If compile/lint fails: Fix issues and return to step 5 (re-run test)
        11. Show compile/lint success output to user
        12. Justify why implementation is minimum
        13. ONLY AFTER completing steps 5-12: Announce post-condition validation
        14. ONLY AFTER validation passes: Transition to GREEN

        🚨 YOU CANNOT TRANSITION TO GREEN UNTIL TEST PASSES, CODE COMPILES, AND CODE LINTS 🚨