RED   → Write failing tests FIRST
GREEN → Implement minimum code to pass
REFACTOR → Improve while keeping green

// 1a. Define input/output types
export interface FeatureInput {
  // ... explicit types, no any
}

export interface FeatureResult {
  success: boolean;
  data?: OutputType;
  error?: string;
}

// 1b. Create stub (throws "Not implemented")
export async function feature(input: FeatureInput): Promise<FeatureResult> {
  throw new Error("Not implemented — write tests first");
}

import { describe, it, expect, vi, beforeEach } from "vitest";
import { feature } from "./feature.js";

// Mock LLM provider if needed
vi.mock("../../providers/index.js", () => ({ ... }));

describe("feature", () => {
  beforeEach(() => vi.clearAllMocks());

  // Group 1: Happy path
  describe("success cases", () => {
    it("processes valid input correctly", async () => { ... });
    it("handles optional parameters", async () => { ... });
  });

  // Group 2: Edge cases
  describe("edge cases", () => {
    it("handles empty input", async () => { ... });
    it("handles maximum boundary values", async () => { ... });
  });

  // Group 3: Error cases
  describe("error handling", () => {
    it("returns error for invalid input", async () => { ... });
    it("handles unexpected errors", async () => {
      await expect(feature({ input: "error" })).resolves.toMatchObject({
        success: false,
      });
    });
  });

  // Group 4: Concurrent access (if applicable)
  describe("concurrent access", () => {
    it("handles parallel calls safely", async () => { ... });
  });
});

pnpm test src/path/feature.test.ts
# Should show: X tests failed ← correct!

pnpm test src/path/feature.test.ts

pnpm test src/path/feature.test.ts

pnpm test:coverage -- --reporter=text src/path/

pnpm check  # typecheck + lint + ALL tests

import { analyzeComplexity } from "./complexity-analyzer.js";

it("detects deeply nested code as high complexity", async () => {
  const code = `
    function nested() {
      if (a) { if (b) { if (c) { if (d) { return 1; } } } }
    }
  `;
  const result = await analyzeComplexity(code);
  expect(result.score).toBeLessThan(60); // high complexity = low score
});

it("registers tool and executes successfully", async () => {
  const registry = createToolRegistry();
  registerMyTool(registry);

  expect(registry.has("myTool")).toBe(true);
  const result = await registry.execute("myTool", { valid: "input" });
  expect(result.success).toBe(true);
});

/tdd implement the new codebase-map tool
/tdd fix the provider timeout bug (with reproducing test first)
/tdd add validation to the quality evaluator