tdd-implementation

name	tdd-implementation
description	Test-Driven Development implementation workflow. RED: write failing test, GREEN: minimum code to pass, REFACTOR: clean up. Includes task metadata requirements, verification, and atomic commit practices.

TDD Implementation

Implement code changes using the Test-Driven Development (RED/GREEN/REFACTOR) cycle. This skill defines the complete workflow from task metadata validation through atomic commit.

Task Metadata

Each task you work on must have the following in its metadata:

{
  "plan": "<plan-name>",
  "type": "spike|bug|task|epic|story",
  "acceptance_criteria": ["..."],
  "relevant_documentation": "",
  "testing_requirements": ["..."],
  "skills": ["..."],
  "learnings": ["..."],
  "verification": {
    "type": "ui-recording|api-test|cli-test|database-check|manual-check|documentation",
    "command": "the proof command — must run the actual system (NOT test/typecheck/lint, those are quality gates)",
    "expected": "what success looks like — observable system behavior"
  }
}

All fields are mandatory — empty arrays are ok. If any are missing, ask the agent team to fill them in and wait to get a response.

Workflow

1. Verify task metadata — All fields are mandatory. If any are missing, ask the agent team to fill them in and wait to get a response.
2. Load skills — Load the skills in the skills property of the task metadata.
3. Read before writing — Read existing code before modifying it. Understand acceptance criteria, verification, and relevant research.
4. Follow existing patterns — Match the style, naming, and structure of surrounding code.
5. One task at a time — Complete the current task before moving on.
6. RED — Write a failing test that captures the expected behavior from the task description. Focus on testing behavior, not implementation details.
7. GREEN — Write the minimum production code to make the test pass.
8. REFACTOR — Clean up while keeping tests green.
9. Verify empirically — Run the task's proof command and confirm expected output.
10. Update documentation — Add/Remove/Modify all relevant JSDoc preambles, explaining "why", not "what".
11. Update the learnings — Add what you learned during implementation to the learnings array in the task's metadata.learnings. These should be things that are relevant for other implementers to know.
12. Commit atomically — Once verified, run the /git-commit skill.

TDD Cycle

Always write failing tests before implementation code. This is mandatory, not optional.

TDD Cycle:
1. RED: Write a failing test that defines expected behavior
2. GREEN: Write the minimum code to make the test pass
3. REFACTOR: Clean up while keeping tests green

RED Phase

• Write a test that captures the expected behavior from the task description
• Focus on testing behavior, not implementation details
• The test must fail before you write any production code
• If the imported module doesn't exist, Jest reports 0 tests found (not N failed) — this is expected RED behavior
• For a Fix task, or a Build task that changes user-visible behavior, include a regression test at the highest practical observation level for the reported surface. If the project has a browser, device, or end-to-end harness for that platform (for example Playwright, Maestro, Detox, Cypress, or an equivalent runtime), the RED test plan must include a deterministic spec against the reported surface, using mocked or seeded data where needed.
• The team lead may not waive, defer, or mark that user-visible regression spec as optional, "if cheap", or equivalent. The only exits are a recorded absence of an end-to-end harness for the affected platform, or a genuine technical blocker with a linked build-ready follow-up ticket created before merge and referenced from the PR and source work item.
• A regression spec is not complete merely because it exists. Completion evidence must prove the spec actually ran and passed in PR CI with a named log line, reporter output, or equivalent execution record. Guard against test.skip, suite-level environment gates, shard filters, and "0 tests" passes.

GREEN Phase

• Write the minimum production code to make the test pass
• Do not optimize, do not add features beyond what the test requires
• The goal is the simplest code that makes the test green

REFACTOR Phase

• Clean up code while keeping all tests green
• Remove duplication, improve naming, simplify structure
• Run tests after every refactor step to confirm nothing breaks

When Stuck

• Re-read the task description and acceptance criteria
• Check relevant research for reusable code references
• Search the codebase for similar implementations
• Ask the team lead if the task is ambiguous — do not guess