tdd

name	tdd
description	Test-Driven Development with Red-Green-Refactor cycle, vertical slices, and tracer bullets
triggers	["/omp:tdd",{"tdd":null}]

TDD — Test-Driven Development

Use this skill when implementing any feature or bugfix using the Red-Green-Refactor cycle. Write the failing test first, write minimal code to pass it, then refactor.

<Do_Not_Use_When>

• Exploratory prototyping — When you are still discovering the problem space and requirements are unclear, writing tests first creates a moving target and wastes cycles. Explore first, then TDD once the interface stabilizes.
• One-off automation scripts — Scripts with no expected reuse, no downstream consumers, and no need for regression coverage. A quick one-liner in a REPL is faster and cleaner.
• Trivial boilerplate — Generating getters/setters, scaffolding files, or copy-paste patterns that carry no behavioral logic.
• UI/visual refinements — Tweaking colors, spacing, or copy where the "right behavior" is subjective and visual inspection beats assertions.
• Learning a new API — When experimenting with unfamiliar SDKs or frameworks, write scratch code to build intuition first. Add tests once the API shape is stable.
• Performance optimization passes — Before measuring, you do not know what is slow. Tests written for correctness can conflict with benchmarks. Keep them separate.

---

Red-Green-Refactor Cycle

The core TDD loop has exactly three phases. Never skip or reorder them.

RED: Write a focused failing test

Write a test that describes the behavior you want. Run it — it must fail. A test that passes before any implementation is written is not a test, it is a false signal.

GREEN: Write minimal code to pass

Write the smallest amount of production code that makes the test pass. Do not write code for future requirements. Do not generalize. Make the test green and stop.

REFACTOR: Clean up with tests green

With the test green, clean up the implementation — remove duplication, improve naming, extract deep modules. Run tests after every edit. If they go red, revert immediately.

Repeat this cycle for each behavioral slice.

---

<Tool_Usage>

Tool	When to Use
Bash (test runner)	Run npm test, pytest, go test, or equivalent to get fast per-file feedback during RED-GREEN cycles.
Write / Edit	Write failing test first (RED), then write minimal production code (GREEN), then clean up (REFACTOR).
mcp__plugin_oh-my-claudecode_t__lsp_diagnostics	Catch type errors and missing imports immediately after edits.
mcp__plugin_oh-my-claudecode_t__lsp_diagnostics_directory	Run full project diagnostics before marking a cycle done.
Grep	Find existing tests for the same module before writing a new one — avoid duplication.
Glob	Locate test files matching the module under development.

Typical cycle:

1. Write a failing test (RED) — Write to the test file.
2. Run the test runner via Bash to confirm the failure.
3. Write minimal code to pass (GREEN) — Edit the production file.
4. Run diagnostics — mcp__plugin_oh-my-claudecode_t__lsp_diagnostics on both files.
5. Refactor (REFACTOR) — Edit production code, confirm tests stay green.
6. Repeat.

---

<Why_This_Exists>

TDD provides a tight feedback loop that keeps implementation anchored to behavior. Without it, code grows inward — implementation details proliferate, coupling increases, and tests (when written at all) fight the code instead of guiding it.

The OMP-specific variant emphasizes vertical slices via tracer bullets rather than horizontal layering. Horizontal TDD (write all tests for Layer A, then all for Layer B) produces integration gaps: every layer compiles in isolation but the system fails end-to-end. Vertical TDD traces one complete path from user input to data storage before moving to the next slice, delivering working software incrementally.

Deep modules are preferred because they minimize the interface surface you must test, making each test more powerful and easier to reason about. A large, well-hidden implementation behind a small interface is easier to verify, easier to refactor, and cheaper to change.

---

RED: Write a focused failing test

A test for a user-authentication module:

// auth.test.ts
import { authenticate } from './auth';

describe('authenticate', () => {
  it('returns a session token when credentials are valid', async () => {
    const token = await authenticate({ username: 'alice', password: 'secret123' });
    expect(token).toMatch(/^[a-z0-9]{32}$/);
  });

  it('throws AuthError when password is incorrect', async () => {
    await expect(
      authenticate({ username: 'alice', password: 'wrong' })
    ).rejects.toThrow('Invalid credentials');
  });
});

Notice: tests describe what the function returns and when it throws — not how it works internally.

---

GREEN: Write minimal code

// auth.ts
import crypto from 'crypto';

export class AuthError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'AuthError';
  }
}

const VALID_CREDENTIALS = { alice: 'secret123' };

export async function authenticate({
  username,
  password,
}: {
  username: string;
  password: string;
}): Promise<string> {
  const expected = VALID_CREDENTIALS[username];
  if (!expected || expected !== password) {
    throw new AuthError('Invalid credentials');
  }
  return crypto.randomBytes(16).toString('hex');
}

This is the minimum code to make both tests pass. It is not the final architecture — it is the seed. The test survives refactoring because it tests behavior, not implementation.

---

REFACTOR: Hide complexity behind a deep module

The first green pass exposes that the credentials check and token generation are interleaved. Refactor to a deep module:

// credentials.ts  (deep module — small interface, large hidden implementation)
const STORE = new Map<string, string>(); // currently in-memory; swap to DB later

export async function checkCredentials(username: string, password: string): Promise<boolean> {
  const stored = STORE.get(username);
  return stored !== undefined && stored === password;
}

export async function addCredential(username: string, password: string): Promise<void> {
  // future: hash before storing
  STORE.set(username, password);
}

The authenticate function becomes a thin, shallow orchestrator that delegates to deep modules. Tests for authenticate do not change — they only test the public interface.

---

Vertical Slice: User signup end-to-end

Slice 1 — Register and retrieve a user

// user.test.ts
it('stores a user and retrieves them by id', async () => {
  const id = await registerUser({ username: 'bob', password: 'pw' });
  const user = await getUser(id);
  expect(user.username).toBe('bob');
});

Write minimal code: in-memory store, registerUser writes to it, getUser reads back.

Slice 2 — Reject duplicate usernames

it('throws DuplicateError when username is already taken', async () => {
  await registerUser({ username: 'bob', password: 'pw' });
  await expect(
    registerUser({ username: 'bob', password: 'pw2' })
  ).rejects.toThrow('Duplicate username');
});

Add the check to the existing registerUser — no new classes, no abstraction layers yet.

Slice 3 — Persist to database

Swap the in-memory store for a real DB adapter. Tests pass unchanged because the interface is the same.

Horizontal TDD would have written all in-memory tests, then all DB tests, then all business-logic tests — producing a large integration gap before any slice works end-to-end. Vertical TDD delivered a working registration flow after Slice 1.

---

<Escalation_And_Stop_Conditions>

Escalate when:

• Test is flaky or environment-dependent — A test that passes locally but fails in CI is noise, not signal. Escalate to omp architect to design a stable test fixture strategy.
• The interface is unstable — If the "right" public API is unclear after 3 cycles, stop. The problem definition is incomplete. Escalate to omp analyst to refine requirements.
• A refactor breaks many tests — Tests that fail because implementation details changed indicate the tests are testing internals. This is a signal to re-examine what the public interface should be. Escalate before continuing.
• You are writing tests that replicate production logic — If your test re-implements the function under test to verify it, you are testing the wrong thing. Escalate to omp verifier for a second opinion.

Stop when:

• All tests in the current slice pass and lsp_diagnostics_directory reports zero errors.
• The per-cycle checklist (below) is satisfied.
• The vertical slice connects all layers — input, business logic, and storage — in a working path.
• Next steps require business decisions (e.g., which user flow to slice next) — those belong to omp analyst or the user.

---

<Per-Cycle_Checklist>

Run through these before marking a TDD cycle complete:

• Is this test focused on a PUBLIC interface, not internals? Test authenticate(params) — not authenticate._tokenCache or any private state.

• Does the test describe BEHAVIOR, not implementation? "returns a session token when credentials are valid" is behavior. "calls crypto.randomBytes" is implementation — avoid it.

• Will this test SURVIVE refactoring? If you refactor credentials.ts internals, does this test still pass? If not, the test is coupled to internals — rewrite it.

• Is the code I wrote the MINIMAL amount to pass? No early optimization. No generalized abstractions. No extra parameters. Write what makes the test pass, nothing more.

• Is this slice vertical — does it span from input to storage? If you only added a DB call without connecting it to the public API, the slice is incomplete.

---

<Final_Checklist>

Before declaring a TDD skill session complete:

• All new test files exist and are committed to the repo alongside production files.
• npm test (or equivalent) runs green with zero failures.
• lsp_diagnostics_directory reports zero errors across the modified package.
• No TODO, HACK, debugger, or console.log statements remain in production or test code.
• Tracer-bullet slices are connected: at least one complete vertical path (input → logic → storage) is working and tested end-to-end.
• Tests are named for the behavior they verify, not the method they call.
• Deep modules are used for complex internals; orchestrators stay thin.
• Any new skill-worthy pattern (3+ repetitions of the same logic) is noted and escalated to omp analyst for skill extraction.