RonanCodes/tdd

TDD

Implement features using strict red-green-refactor cycles. Write the test first. Always.

Usage

/tdd "add search endpoint with fuzzy matching"
/tdd --story US-003

If --story is passed, read the story from .ralph/prd.json for requirements and acceptance criteria.

Detect the Project

Before writing anything, detect:

1. Test framework — scan for jest.config, vitest.config, pytest.ini, go.mod, playwright.config, etc.
2. Test conventions — find existing test files to match naming (*.test.ts, *.spec.ts, test.go, test.py)
3. Test command — check package.json scripts, Makefile, or equivalent
4. Source structure — understand where source and test files live

If no test setup exists, ask the user which framework to use and set it up.

The Cycle

Repeat for each vertical slice:

1. Red — Write a Failing Test

• Break the feature into the thinnest possible vertical slice
• Write ONE test that defines expected behavior for that slice
• Run the test — it MUST fail
• If it passes, the test is not testing anything new — rewrite it

2. Green — Make It Pass

• Write the MINIMUM code to make the test pass
• No extra features, no future-proofing, no "while I'm here" additions
• Run the test — it MUST pass

3. Refactor — Clean Up

• Improve naming, extract duplication, simplify logic
• Run tests after EACH change — they must stay green
• Do NOT add new behavior during refactor

Bug & user-feedback mode (reproduce-first)

When the trigger is a bug or user feedback (not a new feature), the cycle is the same red-green-refactor, but RED means reproduce the reported scenario, not invent a spec. A production bug is a gap your tests did not cover; the report is the cheapest spec you will ever get. (Canon: canon/sentry-user-issues-tdd.md.)

1. Red — reproduce the issue as a failing test

Translate the report into the smallest test that fails for the user's reason. Do whatever it takes to actually SEE the issue first — pick the cheapest level that genuinely reproduces it:

• Unit when the cause is pure logic (a filter, a mapper, a planner). Construct the exact inputs from the report (e.g. a household that excludes "mushroom" + a catalogue with a Dutch "champignon" recipe) and assert the correct behaviour. Default to this — fastest, most precise.
• Integration / server-fn when it spans a server boundary or the DB.
• e2e / Playwright / a real browser when it's a flow you can only see live: mobile vs desktop, signed-out render, a slow/hanging POST, an auth-cookie race, "tap then it bounces". Use real accounts, click through, add waits/timing, watch the network — recreate the actual scenario. CI-able is ideal; a one-off live repro that proves the cause is also fine.

Run it. Confirm it fails, and fails for the RIGHT reason (read the failure — a test that fails for an unrelated reason proves nothing). "It's obvious, I'll just fix it" is exactly when this step gets skipped and the wrong thing gets fixed. The failing test is the proof you understood the bug.

2. Green — make it work, do NOT optimize

Make the MINIMUM change that turns the test green. Resist making it elegant or fast yet — get it correct and working first. No drive-by refactors, no premature optimisation. Run the test: it must pass and the rest of the suite must stay green.

3. Refactor — THEN make it better (before you commit)

Only once it's green: improve the code — naming, duplication, clarity, and now any optimisation that's actually warranted. Tests stay green after every change; add no new behaviour. The separation is the point: correctness first (green), quality second (refactor). Optimising before it works is how you ship a fast wrong answer.

Ship the regression test in the same change as the fix — never as a follow-up (the follow-up that never comes is the default outcome). For Sentry-tracked bugs, pair it with the resolvedInNextRelease reopen-on-recurrence backstop (/ro:sentry).

Vertical Slices

Each cycle implements a thin end-to-end slice, not a horizontal layer.

Good slices (thin, vertical, testable):

• Search endpoint exists and returns 200 with results
• Search filters by category and returns filtered results
• UI renders search input and displays results from API

Bad slices (thick, horizontal):

• Build the entire database layer
• Implement all API endpoints
• Create all UI components

After Each Cycle

Report:

## Cycle N: [slice description]
- RED: [test written, confirmed failing]
- GREEN: [code written, test passing]
- REFACTOR: [what was cleaned up]
- Status: N of ~M slices complete

Integration with Ralph

If working on a story from .ralph/prd.json, update the story's passes field and append progress to .ralph/progress.txt after all slices are complete.

Rules

1. Never write implementation before the test
2. Never write more than one test at a time
3. Never skip the red step, seeing the test fail proves it tests something real
4. Keep each cycle under 15 minutes of work; if it's bigger, split the slice
5. If stuck, step back and check if the slice is too big

Why TDD is the load-bearing feedback loop for agents

The quality of an agent's feedback loop sets the ceiling on its output quality. TDD instruments the code before the implementation lands, which makes it much harder for the agent to "cheat" the test (write the implementation first, then write a test that conveniently matches). Without good feedback loops the agent codes blind, no matter how good the prompt is.

This is also why deep modules work so well with TDD: one test boundary around a deep module covers a lot of behaviour, so each red-green cycle exercises a meaningful slice rather than a thin shell. Background: llm-wiki-ai-research:deep-modules-for-ai.