<domain_overview>

🧪 TDD MASTERY: THE IRON LAW

Philosophy: If you didn't watch the test fail, you don't know if it tests the right thing. TDD is not optional—it's the foundation of trustworthy code. TEST-FIRST INTEGRITY MANDATE (CRITICAL): Never write production code before a test exists and has been seen failing. AI-generated code often attempts to write implementation and tests simultaneously or implementation first. You MUST strictly adhere to the Red-Green-Refactor cycle. Any code submitted without a preceding failing test or that generates tests after the implementation must be rejected as "Legacy Code on Arrival".

---

🚨 THE IRON LAW

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Write code before the test? Delete it. Start over.

No exceptions:

• Don't keep it as "reference"
• Don't "adapt" it while writing tests
• Don't look at it
• Delete means delete

Implement fresh from tests. Period. </domain_overview> <core_workflow>

🔴 RED-GREEN-REFACTOR CYCLE

Phase 1: RED - Write Failing Test

Write one minimal test showing what should happen.

Good Example:

test('retries failed operations 3 times', async () => {
  let attempts = 0;
  const operation = () => {
    attempts++;
    if (attempts < 3) throw new Error('fail');
    return 'success';
  };

  const result = await retryOperation(operation);

  expect(result).toBe('success');
  expect(attempts).toBe(3);
});

Clear name, tests real behavior, one thing

Bad Example:

test('retry works', async () => {
  const mock = jest.fn()
    .mockRejectedValueOnce(new Error())
    .mockResolvedValueOnce('success');
  await retryOperation(mock);
  expect(mock).toHaveBeenCalledTimes(2);
});

Vague name, tests mock not code

Requirements:

• One behavior per test
• Clear, descriptive name
• Real code (mocks only if unavoidable)

Phase 2: VERIFY RED - Watch It Fail

MANDATORY. Never skip.

npm test path/to/test.test.ts
# or
pytest tests/path/test.py::test_name -v

Confirm:

• Test fails (not errors)
• Failure message is expected
• Fails because feature missing (not typos)

Test passes? You're testing existing behavior. Fix test.

Test errors? Fix error, re-run until it fails correctly.

Phase 3: GREEN - Minimal Code

Write simplest code to pass the test.

Good:

async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
  for (let i = 0; i < 3; i++) {
    try {
      return await fn();
    } catch (e) {
      if (i === 2) throw e;
    }
  }
  throw new Error('unreachable');
}

Just enough to pass

Bad:

async function retryOperation<T>(
  fn: () => Promise<T>,
  options?: {
    maxRetries?: number;
    backoff?: 'linear' | 'exponential';
    onRetry?: (attempt: number) => void;
  }
): Promise<T> {
  // YAGNI - You Aren't Gonna Need It
}

Over-engineered

Don't add features, refactor other code, or "improve" beyond the test.

Phase 4: VERIFY GREEN - Watch It Pass

MANDATORY.

npm test path/to/test.test.ts

Confirm:

• Test passes
• Other tests still pass
• Output pristine (no errors, warnings)

Test fails? Fix code, not test.

Other tests fail? Fix now.

Phase 5: REFACTOR - Clean Up

After green only:

• Remove duplication
• Improve names
• Extract helpers

Keep tests green. Don't add behavior.

Phase 6: COMMIT

git add tests/path/test.ts src/path/file.ts
git commit -m "feat: add specific feature with tests"

Repeat for next behavior.

---

</core_workflow>

<quality_standards>

📋 GOOD TEST QUALITIES

---

🚫 COMMON RATIONALIZATIONS (ALL INVALID)

---

🚨 RED FLAGS - STOP AND START OVER

If you catch yourself:

• Writing code before test
• Test passes immediately
• Can't explain why test failed
• Tests added "later"
• "Just this once"
• "I already ma

...