Test Driven Development

Test-Driven Development (TDD)

Purpose

Stage: Implement — the rigid core loop, applied inside every incremental-implementation slice.

Write the test first. Watch it fail. Write minimal code to pass.

Core principle: if you didn't watch the test fail, you don't know if it tests the right thing.

This is the suite's one non-negotiable loop. Everything upstream (intent → prd → acceptance.md) converges here: each signed Given/When/Then scenario becomes a failing test before a line of production code exists, realized by judgment in the project's real test framework — there is no Cucumber/step-def engine. In the autonomous run no human watches you code, so the only proof a test tests something real is that you saw it go RED first.

Violating the letter of the rules is violating the spirit of the rules.

When to use / when to skip

Always — structurally applied during every incremental-implementation slice:

• New features
• Bug fixes
• Refactoring
• Behavior changes

Exceptions (the only ones — they mirror the test-first commit hook's allowlist):

• Throwaway prototypes (e.g. frontend-design exploration it discards)
• Generated code
• Configuration files

Thinking "skip TDD just this once"? Stop. That's rationalization. Test-first ordering is hook-enforced: a test file must change in the same commit as impl, or earlier on the branch. --no-verify and SKIP-style bypasses are forbidden — fix the order, don't dodge the hook.

Inputs

Consumes: acceptance.md — the signed BDD prose contract (from the acceptance-criteria skill). Sections this skill reads:

• Given/When/Then scenarios — behavioral-only (happy + error/edge + security-observable). Each becomes one test.
• Feature-namespaced scenario ids (e.g. PWR-A1) — carry the id in each test's name/description so quality-verification can keep its exercised / not-reachable ledger by id.
• status: — must be signed.

Also handed in by incremental-implementation / the orchestrator: the slice's plan steps (which files, which tests) and the slice's declared Regression surface.

Refuse to run if:

• acceptance.md is absent, or
• acceptance.md status: is draft (unsigned, or re-invalidated by a later prd.md edit).

A draft/absent contract means the human-signed oracle isn't fixed — implementing against it bakes in an unsigned target. Stop and route back to the Spec gate.

Process

Each signed scenario in acceptance.md becomes a failing test first; you write the minimal code to turn it green; you refactor under green. You translate Given/When/Then into a real test by judgment, not via a code generator. Name each test for its scenario id (PWR-A1) so the realization is traceable.

Red-Green-Refactor

digraph tdd_cycle {
    rankdir=LR;
    red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
    verify_red [label="Verify fails\ncorrectly", shape=diamond];
    green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
    verify_green [label="Verify passes\nAll green", shape=diamond];
    refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
    next [label="Next", shape=ellipse];

    red -> verify_red;
    verify_red -> green [label="yes"];
    verify_red -> red [label="wrong\nfailure"];
    green -> verify_green;
    verify_green -> refactor [label="yes"];
    verify_green -> green [label="no"];
    refactor -> verify_green [label="stay\ngreen"];
    verify_green -> next;
    next -> red;
}

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.

RED - Write Failing Test

Write one minimal test showing what should happen.

const result = await retryOperation(operation);

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

Clear name carrying the scenario id, tests real behavior, one thing
</Good>

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

Vague name, no scenario id, tests mock not code

Requirements:

• One behavior
• Clear name (carry the acceptance.md scenario id)
• Real code (no mocks unless unavoidable)

Verify RED - Watch It Fail

MANDATORY. Never skip.

npm test path/to/test.test.ts

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.

GREEN - Minimal Code

Write simplest code to pass the test.

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

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.

REFACTOR - Clean Up

After green only:

• Remove duplication
• Improve names
• Extract helpers

Keep tests green. Don't add behavior.

Repeat

Next failing test for the next scenario / feature.

Good Tests

Frozen artifacts under retry (gate-erosion is a HALT)

Safety rail 4 (../../references/safety-rails.md) governs this and is not restated here: the consumed acceptance.md scenarios, the RED tests you wrote for them, and the slice's declared Regression surface are frozen while the slice is being made to pass; weakening an assertion, deleting or skipping a RED test, narrowing the surface, or editing a scenario is gate-erosion → HALT (flip gate: agent → you), and the halt names the artifact. docs/design.md is read-only on the same rail.

What this stage adds is the reason the rail bites hardest here. You are the party that writes the oracle. In the autonomous run nobody watches you write the test that will later judge your code, so the window between "this test is red" and "this test is green" is the one place a false green can be manufactured at zero cost — the edit is one line and it is in a file you already have open. That is why the freeze starts the moment the test goes red rather than at Verify.

Reporting a scenario unreachable is not weakening it. If this slice cannot construct a scenario's Given — the state depends on work that does not exist yet — record the id as not reachable and carry on. The scenario stays in acceptance.md, unproven, and reaches a person through the required PR acknowledgement line. Nothing stopped being checked, so nothing halts. Only removing a scenario from the contract, or rewriting it to assert less, is the erosion.

Fix the code, never the oracle. A frozen failing test is information; a relaxed test is a silent false-green.

Rationalizations

"I'll write tests after to verify it works" — Tests written after code pass immediately, which proves nothing: might test the wrong thing, might test implementation not behavior, might miss edge cases, you never saw it catch the bug. Test-first forces you to see it fail.

"I already manually tested all the edge cases" — Manual testing is ad-hoc: no record, can't re-run, easy to forget under pressure. "It worked when I tried it" ≠ comprehensive.

"Deleting X hours of work is wasteful" — Sunk cost. The time is gone. Keeping code you can't trust is technical debt.

"TDD is dogmatic, being pragmatic means adapting" — TDD IS pragmatic: finds bugs before commit, prevents regressions, documents behavior, enables refactoring. "Pragmatic" shortcuts = debugging in production = slower.

"Tests after achieve the same goals — it's spirit not ritual" — No. Tests-after answer "what does this do?"; tests-first answer "what should this do?" Tests-after are biased by your implementation.

Red flags

STOP and start over (or HALT the slice) on any of these:

• Code before test
• Test after implementation
• Test passes immediately
• Can't explain why test failed
• Tests added "later"
• Rationalizing "just this once"
• "I already manually tested it"
• "Tests after achieve the same purpose"
• "It's about spirit not ritual"
• "Keep as reference" or "adapt existing code"
• "Already spent X hours, deleting is wasteful"
• "TDD is dogmatic, I'm being pragmatic"
• "This is different because..."

Gate-erosion red flags (HALT the slice, flip gate: agent → you):

• Weakening/deleting/skipping a frozen RED test to make a slice pass
• Editing an acceptance.md scenario mid-retry
• Narrowing the declared Regression surface to dodge a failure
• Editing docs/design.md so the built surface matches it — read-only at any moment, retry or not
• Halting for gate erosion without naming the artifact that was about to change

The first group means: delete code, start over with TDD. The second group means: stop, do not ship.

Verification (ending criteria)

This is where BDD binds: every signed acceptance.md scenario reachable in this slice has a test that failed first and now passes, and each test names its scenario id.

Before marking the slice's implementation complete:

• Every reachable acceptance.md scenario has a test (named with its id)
• Every new function/method has a test
• Watched each test fail before implementing
• Each test failed for the expected reason (feature missing, not typo)
• Wrote minimal code to pass each test
• All tests pass
• Output pristine (no errors, warnings)
• Tests use real code (mocks only if unavoidable)
• Edge cases and errors covered
• No frozen test/acceptance/surface was weakened during retries

Can't check all boxes? You skipped TDD. Start over.

Example: Bug Fix

Bug: Empty email accepted.

RED

test('PWR-A2: rejects empty email', async () => {
  const result = await submitForm({ email: '' });
  expect(result.error).toBe('Email required');
});

Verify RED

$ npm test
FAIL: expected 'Email required', got undefined

GREEN

function submitForm(data: FormData) {
  if (!data.email?.trim()) {
    return { error: 'Email required' };
  }
  // ...
}

Verify GREEN

$ npm test
PASS

REFACTOR — extract validation for multiple fields if needed.

When Stuck

Debugging Integration

Bug found? Write a failing test reproducing it, then follow the TDD cycle. The test proves the fix and prevents regression. Never fix bugs without a test — this also feeds debugging-and-error-recovery: the reproducer test is the "guard" step.

Final Rule

Production code → test exists and failed first
Otherwise → not TDD

Outputs & handoff contract

Emits: tests + code into the slice's worktree diff —

• passing tests, one per realized acceptance.md scenario (named with the scenario id), each watched RED before its production code existed;
• the minimal production code that turns them green;
• output pristine (no errors/warnings); all prior tests still green.

Stable handoff facts (what downstream consumes):

• Each test carries its scenario id (PWR-A1) → quality-verification reads these to build its exercised / not-reachable ledger in qa.md; the evaluator's testing_strategy floor and the pull-request code-cold verifier rely on the RED tests being unweakened.
• The RED tests + acceptance.md + Regression surface are now the slice's frozen oracle (see Frozen artifacts under retry).
• A scenario not reachable in this slice is not silently skipped — record its id so qa.md and the PR body carry the required not-reachable ack. Unreachable is honest reporting, and it never halts a slice.

STATE.md: test-driven-development does not drive the board itself (the orchestrator owns STATE.md). It runs while the slice is impl; on green-and-pristine the slice is ready for incremental-implementation to complete and hand to quality-verification (verify).

Testing Anti-Patterns

When adding mocks or test utilities, read references/testing-anti-patterns.md to avoid common pitfalls (AP1–AP5):

• Testing mock behavior instead of real behavior
• Adding test-only methods to production classes
• Mocking without understanding dependencies
• Incomplete mocks (mirror the real structure)
• Integration tests as an afterthought

Subagents

For a fresh-context, code-cold pass, dispatch the test-engineer agent (agents/test-engineer.md) as an independent subagent. This skill is the method; the agent is the role that applies it with no prior context — preserving maker≠checker. Reach for it when a person wants a single code-cold audit of whether a slice's tests are honest outside a run, or on a platform with no skill tool. Inside a run this skill is dispatched as itself — there is no role to play on top of it.