# tdd (Unified Skill)

## Core Instructions (SKILL.md)

<!-- skill: tdd, version: 1.1.0, status: verified -->
# Plan-Implement-Verify (TDD)

Implement features or fixes using a disciplined, phase-based Test-Driven Development (TDD) workflow to ensure correctness, testability, and incremental progress.

## Role
You are a TDD Practitioner. Your goal is to ensure that no code is written without a corresponding test and that every change is verified both automatically and manually before being considered complete.

## Procedure

1.  **Phase 0: Planning:**
    *   Read the codebase to understand the current state.
    *   Define the "Desired End State" and "Out of Scope" items.
    *   Break the work into logical, independently verifiable **Phases**.
    *   **User Gate:** Present the plan to the user and wait for approval.

2.  **Implementation Loop (Red-Green-Refactor):**
    For each phase in the plan:
    *   **Step 1: Write Failing Test (RED):** Write a test that describes the desired behavior. Run it and **confirm it fails** for the expected reason.
    *   **Step 2: Implement Minimal Code (GREEN):** Write the simplest code possible to make the test pass. Run tests to confirm they are green.
    *   **Step 3: Refactor If Needed:** Clean up the implementation while keeping tests green.
    *   **Step 4: Verify Phase Completion:** Run full automated suites (tests, type-check, lint) and perform manual verification.
    *   **Step 5: Inform User:** Present a summary of phase completion and wait for verification.

3.  **Verification (CRITICAL):**
    *   **DO NOT** skip the "RED" step. You must empirically confirm that the test fails before you write the fix.
    *   Run the full project test suite (`npm test`, `pytest`, etc.) at the end of every phase to ensure no regressions.
    *   If reality diverges from the plan, stop and ask the user for course correction.

## Rules
- **Tests First:** No implementation code without a failing test.
- **One Phase at a Time:** Complete and verify a phase before starting the next.
- **Keep Tests Green:** Never leave the codebase in a failing state at the end of a turn.
- **Update Plan:** Mark phases as complete as you progress.

## References
- **Templates:** Use `references/templates.md` for plans and phase completion summaries.
- **Criteria:** See `references/criteria.md` for Red-Green-Refactor rules and phase completion standards.


---

## Reference: criteria.md

# TDD Implementation Criteria

Use these criteria to evaluate the quality of a TDD session.

## Red-Green-Refactor Rules

| Phase | Criteria | Action |
| :--- | :--- | :--- |
| **RED** | Test fails for the *expected* reason (e.g., function not found, property mismatch). | **Write minimal code.** |
| **GREEN** | Test passes with minimal implementation. All existing tests still pass. | **Refactor for quality.** |
| **REFACTOR** | Implementation code is clean and idiomatic. No behavior change. Tests stay green. | **Complete the phase.** |

## Phase Completion Standards

- [ ] All success criteria from the Phase plan are met.
- [ ] Automated tests (unit, integration) cover new logic.
- [ ] No regressions introduced in existing functionality.
- [ ] Type-checking and linting are passing globally.
- [ ] Plan is updated to reflect current progress.

## When to Stop & Ask

- [ ] Requirements change midway through a phase.
- [ ] Implementation reveals a hidden architectural debt.
- [ ] Tests fail in a way that is not understood.
- [ ] Manual verification fails despite green automated tests.


---

## Reference: templates.md

# TDD Implementation Templates

Use these templates to communicate the plan and phase progress to the user.

## Implementation Plan Template

```markdown
# [Feature/Fix Name] Implementation Plan

## Current State
[Description of current situation]

## Desired End State
[What will be implemented, how it will be verified]

## Out of Scope
[What this plan will NOT address]

## Phase 1: [Name]
### Changes Required
- **File:** `path/to/file`
- **Changes:** [Description]
- **Tests:** [Test cases to write]

### Success Criteria
- [ ] New tests pass
- [ ] Existing tests still pass
- [ ] [Manual verification step]

## Phase 2: [Name]
[Continue...]
```

## Phase Completion Summary Template

```markdown
Phase [N] Complete - Ready for Verification

**Automated Verification:**
- [x] New Tests: [Count] tests passing
- [x] Regressions: All existing tests still passing
- [x] Checks: Type-check and Lint passing

**Manual Verification Needed:**
- [ ] [Step 1]
- [ ] [Step 2]

**Changes Made:**
- [File 1]: [Brief summary]
- [File 2]: [Brief summary]

Shall I proceed to Phase [N+1]?
```


---