codename-inc/spectre-tdd

TDD: Test-Driven Development Methodology

Execute tasks using strict TDD (RED → GREEN → REFACTOR). Outcome: Tasks completed with Happy/Failure tests passing, minimal code shipped.

Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Wrote code before the test? Delete it. Start over. Don't keep it as "reference." Don't "adapt" it. Delete means delete. Implement fresh from tests.

Rules

• 2 tests per Test Opportunity (TO): 1 Happy path, 1 Failure path — then stop
• Scoped execution: Never run repo-wide tests; use --testPathPattern, --findRelatedTests, or per-file lint
• YAGNI: No abstractions unless test forces it or ≥2 call sites exist
• Anti-flake: Use fake timers, stubs, seeded RNG

---

Step 1 - Generate TDD TODO List

• Action — ParseTaskList: Extract tasks from ARGUMENTS or thread context
  • If no clear tasks → stop and ask for guidance
• Action — IdentifyTestOpportunities: Derive TOs (smallest behavior unit: function, route, bug fix, acceptance criterion)
• Action — TransformToTDD: Convert each TO to cycle using TodoWrite:
  • RED: Happy — {test} → RED: Failure — {test} → GREEN: Minimal impl → REFACTOR: Tidy → COMMIT
• Action — VerifyScope: Confirm TODO contains ONLY assigned tasks

Step 2 - RED Phase: Write Failing Tests

• Action — WriteHappyTest: Write first failing test (happy path)
  • Execute only this test/file, not entire suite
• Action — WriteFailureTest: Write second failing test (primary failure mode)
• Action — VerifyRed: MANDATORY — Confirm each test:
  • Fails (not errors)
  • Fails for expected reason (feature missing, not typo)
  • If passes → you're testing existing behavior; fix test

Step 3 - GREEN Phase: Minimal Implementation

• Action — ImplementMinimal: Write least code to pass tests
  • No extra branches, params, or dependencies unless test forces them
• Action — VerifyGreen: MANDATORY — Run tests (narrowest scope)
  • If fail → fix code, not test
  • Remove any speculative code not forced by tests

Step 4 - REFACTOR Phase: Clean Code

• Action — RefactorSafely: Improve only if duplication ≥3 OR readability materially improves
  • Keep tests green; If tests fail → revert
• Action — HandleLintFailures: Apply in order until clear:
  1. Guard clauses, split compound expressions
  2. Extract tiny private helpers (same file)
  3. Hoist literals to file constants
  4. Split into orchestrator + helpers
  5. Only if still failing: same-directory helper module

Step 5 - Loop or Complete

• If more TOs → return to Step 2
• Else → proceed to Step 6

Step 6 - Commit & Report

• Action — CommitCode: Conventional format (feat({task}): description)
• Action — GenerateReport:
  • Summary: Tasks completed, test status (✅ Happy ✅ Failure), files modified
  • Artifacts: Test helpers, mocks, fixtures created
  • API Surface: New/modified exports with signatures
  • Patterns: Code/testing patterns to follow
  • Deferred: Coverage gaps for follow-up

---

Red Flags — STOP and Restart

If any of these occur, delete code and start over with TDD:

| Red Flag | Why It's Wrong | |----------|----------------| | Code written before test | Violates Iron Law | | Test passes immediately | Testing existing behavior, not new | | Can't explain why test failed | Don't understand what you're testing | | "Just this once" thinking | Rationalization — TDD has no exceptions | | Keeping code "as reference" | You'll adapt it; that's tests-after |

When Stuck

| Problem | Solution | |---------|----------| | Don't know how to test | Write wished-for API first, then assert on it | | Test too complicated | Design too complicated — simplify interface | | Must mock everything | Code too coupled — use dependency injection | | Test setup huge | Extract helpers; still complex? Simplify design |

Pre-Completion Checklist

Before marking complete, verify:

• [ ] Every new function has a test
• [ ] Watched each test fail before implementing
• [ ] Each failure was for expected reason
• [ ] Wrote minimal code to pass
• [ ] All tests pass, output clean
• [ ] Mocks used only when unavoidable