# How to Use the TDD Workflow Skill in ECC: A Complete Guide to Test‑Driven Development

> Master the TDD workflow skill in ECC with this guide. Learn to enforce RED GREEN refactor cycles, achieve 80% code coverage, and use Git checkpoints for disciplined development.

- Repository: [Affaan Mustafa/ECC](https://github.com/affaan-m/ECC)
- Tags: how-to-guide
- Published: 2026-05-26

---

**The TDD Workflow skill in ECC enforces a disciplined test‑driven development cycle through RED‑GREEN‑refactor gates, mandatory 80% code coverage, and semantic Git checkpoints.**

The **ECC** (Effective Codebase Companion) repository by affaan‑m provides knowledge‑based skills rather than executable libraries. The **TDD Workflow** skill, defined in [`skills/tdd-workflow/SKILL.md`](https://github.com/affaan-m/ECC/blob/main/skills/tdd-workflow/SKILL.md), guides developers and AI agents through a rigorous TDD lifecycle—from capturing user journeys to verifying coverage—using standard npm scripts and semantic Git commits.

## The Seven Phases of the TDD Workflow Skill

The skill organizes development into seven distinct phases that enforce test‑first discipline. Each phase maps to specific sections in [`skills/tdd-workflow/SKILL.md`](https://github.com/affaan-m/ECC/blob/main/skills/tdd-workflow/SKILL.md) and must be completed sequentially.

### 1. Write User Journeys

Capture functional intent using the standard "As a… I want… so that…" format. This phase appears in the *User Journeys* section of [`SKILL.md`](https://github.com/affaan-m/ECC/blob/main/SKILL.md) at line 65. Defining the journey establishes a business‑level goal that drives all subsequent test design.

### 2. Generate Test Cases

Derive concrete test cases (unit, integration, and Playwright E2E) from the user journey. The *Generate Test Cases* block at line 74 provides skeletons for Jest, Vitest, or Playwright. This step creates the executable specifications that validate the implementation.

### 3. RED Gate: Force Test Failure

Run the test suite and confirm that new tests fail. According to [`SKILL.md`](https://github.com/affaan-m/ECC/blob/main/SKILL.md) line 97, the **RED gate** guarantees that the test truly captures missing functionality rather than passing vacuously. Execute:

```bash
npm test

```

The failure must be intentional and diagnostic.

### 4. Implement Minimal Code

Write the smallest amount of production code necessary to move the test from red to green. The *Implement Code* snippet at line 26 emphasizes focused implementations that satisfy the specific assertion, not future‑proof over‑engineering.

### 5. GREEN Gate: Verify Success

Re‑run the test suite to confirm all tests pass. The **GREEN gate** at line 38 validates that the feature works as intended. Only after this confirmation should you proceed to cleanup.

### 6. Refactor While Green

Clean up implementation details—improving readability, removing duplication, or optimizing performance—while keeping the test suite green. The *Refactor* section at line 54 permits structural improvements only when the safety net of passing tests is active.

### 7. Verify Coverage Thresholds

Execute the coverage script and enforce a minimum of **80%** code coverage. The *Verify Coverage* directive at line 66 requires running:

```bash
npm run test:coverage

```

If coverage falls below the threshold, add edge‑case tests for error handling, empty inputs, or boundary conditions until the report satisfies the requirement.

## Git Checkpoint Strategy

The skill mandates **semantic Git checkpoints** after each RED, GREEN, and optional refactor step. As documented at line 50 of [`SKILL.md`](https://github.com/affaan-m/ECC/blob/main/SKILL.md), these commits create an auditable history that can be rolled back or bisected.

Use conventional commit prefixes:

- `test:` when adding or modifying test files during the RED phase
- `fix:` or `feat:` when implementing code to pass tests during the GREEN phase
- `refactor:` when cleaning up code without changing behavior

Example workflow:

```bash

# RED phase

git add src/lib/searchMarkets.test.ts
git commit -m "test: add unit test for semantic search markets"

# GREEN phase

git add src/lib/searchMarkets.ts
git commit -m "fix: implement searchMarkets to satisfy test"

# Refactor phase

git add src/lib/searchMarkets.ts
git commit -m "refactor: simplify market result generation"

```

## Practical Implementation: Building a Search Feature

The following example demonstrates the complete workflow using a semantic search utility. This pattern applies to any TypeScript or JavaScript project using ECC.

### Step 1: Create the Failing Unit Test (RED)

Create [`src/lib/searchMarkets.test.ts`](https://github.com/affaan-m/ECC/blob/main/src/lib/searchMarkets.test.ts) with a specification that intentionally fails because the implementation does not yet exist:

```typescript
// src/lib/searchMarkets.test.ts
import { searchMarkets } from './searchMarkets';

describe('Semantic Search', () => {
  it('returns relevant markets for a query', async () => {
    const results = await searchMarkets('election');
    expect(results).toHaveLength(3);
    expect(results[0].name).toContain('election');
  });
});

```

Run the test to satisfy the RED gate:

```bash
npm test

```

### Step 2: Implement Minimal Code (GREEN)

Create [`src/lib/searchMarkets.ts`](https://github.com/affaan-m/ECC/blob/main/src/lib/searchMarkets.ts) with the smallest viable implementation:

```typescript
// src/lib/searchMarkets.ts
export async function searchMarkets(query: string) {
  // Minimal stub to satisfy the test
  return [
    { id: '1', name: `${query} results 1` },
    { id: '2', name: `${query} results 2` },
    { id: '3', name: `${query} results 3` },
  ];
}

```

Re‑run tests to confirm the GREEN gate:

```bash
npm test

```

Commit the changes:

```bash
git add src/lib/searchMarkets.ts src/lib/searchMarkets.test.ts
git commit -m "fix: implement searchMarkets to satisfy semantic search test"

```

### Step 3: Refactor and Verify Coverage

Improve the implementation while maintaining behavior:

```typescript
// src/lib/searchMarkets.ts
export async function searchMarkets(query: string) {
  const base = `${query} results`;
  return Array.from({ length: 3 }, (_, i) => ({
    id: `${i + 1}`,
    name: `${base} ${i + 1}`,
  }));
}

```

Verify coverage meets the 80% threshold:

```bash
npm run test:coverage

```

If the report shows gaps, add tests for edge cases (empty strings, special characters, error states). Once green and covered, commit:

```bash
git add src/lib/searchMarkets.ts
git commit -m "refactor: clean up searchMarkets implementation"

```

## Summary

- The **TDD Workflow skill** in ECC is defined in [`skills/tdd-workflow/SKILL.md`](https://github.com/affaan-m/ECC/blob/main/skills/tdd-workflow/SKILL.md) and provides a knowledge‑based guide rather than executable code.
- The workflow enforces a **RED‑GREEN‑refactor loop** with explicit gates at lines 97 (RED), 38 (GREEN), and 54 (refactor).
- **80% code coverage** is mandatory and verified via `npm run test:coverage` as specified at line 66.
- **Semantic Git checkpoints** after each phase provide traceability and rollback capability (line 50).
- The skill is language‑agnostic but expects standard npm scripts (`npm test`) and works seamlessly with Jest, Vitest, or Playwright.

## Frequently Asked Questions

### What is the ECC TDD Workflow skill and where is it located?

The ECC TDD Workflow skill is a knowledge artifact stored at [`skills/tdd-workflow/SKILL.md`](https://github.com/affaan-m/ECC/blob/main/skills/tdd-workflow/SKILL.md) in the affaan‑m/ECC repository. Unlike traditional libraries, it contains no executable code; instead, it provides step‑by‑step instructions for executing test‑driven development with strict coverage and Git discipline.

### How does the RED gate prevent false positives in ECC TDD?

The RED gate, defined at line 97 of [`SKILL.md`](https://github.com/affaan-m/ECC/blob/main/SKILL.md), requires developers to run tests immediately after writing them and confirm they fail. This ensures the test is actually exercising the intended functionality rather than passing due to incorrect assertions or stubbed dependencies. A test that never fails cannot verify that implementation changes cause it to pass.

### What happens if my code coverage drops below 80% during the workflow?

The skill blocks completion of the TDD cycle until coverage meets the 80% threshold specified at line 66. You must add additional test cases covering edge cases, error paths, or boundary conditions, then re‑run `npm run test:coverage`. Only when the report shows the required percentage can you proceed to the final Git checkpoint.

### Can I use the TDD Workflow skill with testing frameworks other than Jest?

Yes. While the examples in [`SKILL.md`](https://github.com/affaan-m/ECC/blob/main/SKILL.md) reference Jest, Vitest, and Playwright, the skill is framework‑agnostic. It requires only that your [`package.json`](https://github.com/affaan-m/ECC/blob/main/package.json) defines standard npm scripts (`npm test` for execution and `npm run test:coverage` for coverage reporting). Any testing tool that exposes these CLI commands integrates seamlessly with the ECC TDD Workflow skill.