TDD Task

4. Red — write a failing test

MANDATORY GATE — do NOT write any implementation code until this step is complete.

The goal is a test that compiles, runs, and fails with an assertion error — not a compile error. A compile error proves the code doesn't exist yet; an assertion error proves the current behavior is wrong.

Unit/integration tests:

1. Create a stub — write the new method/class with a minimal implementation (return null, return a hardcoded wrong value, throw TODO()). Just enough to compile.
2. Write assertions — add tests that assert the correct behavior against the stub. They compile and run but FAIL with assertion errors.
3. Run /test *FilterPattern (or your build tool's test runner) and confirm RED (test must fail with an assertion error).

Playwright/E2E tests:

1. Write the test directly — it runs against the full app, no stub needed. Navigate, interact, assert on expected UI state.
2. Run the test — it fails because the UI/behavior doesn't exist yet. That's RED.
3. Confirm RED (test must fail).

When Step 3 required BOTH a service test AND an E2E test: write the service/unit test first and get it RED, then write the Playwright test and get it RED too. Both must be failing before you start Step 5.

<rules>
- If you cannot write a test, you MUST use AskUserQuestion to explain why and get explicit approval before skipping. Do not rationalize the skip yourself.
- Template/view changes often have testable service or controller behavior behind them — don't use "it's just a template change" as a reason to skip.
- If the change is user-observable, a service/unit test alone is NOT sufficient — you also need a Playwright E2E test per the rule in Step 3.
- The test name should describe the expected behavior (e.g. `Should transition to REVEAL when voting ends` not `Fix end button`)
- If the change requires a DB migration, run the migration and codegen first (check `references/project.md` for the exact commands)
</rules>

5. Green — make the test(s) pass

Write the minimum code to make the failing test(s) pass.

1. Compile the project (check references/project.md for the compile command)
2. Run /test *FilterPattern — confirm GREEN on the service/unit test. Fix inline and re-run if needed.
3. If Step 3 required a Playwright E2E test: run it too and confirm GREEN. For a UI-wiring change, you may need to restart the app (/restart, or rebuild your app manually) before the Playwright run picks up backend changes.
4. Do not proceed to Step 6 until every test you wrote in Step 4 is green.

6. Refactor

Run /simplify (or review manually) to check changed code for reuse, quality, and efficiency. Then clean up anything remaining: remove duplication, extract methods if needed, ensure naming is consistent with surrounding code.

Run /test *FilterPattern — confirm still green after refactoring.

7. Verify

• Non-user-observable changes (background jobs, internal refactors, generated code): service/unit test output is sufficient proof.
• User-observable changes (any route, template, or HTMX/JS flow a user can hit): the Playwright E2E test you wrote in Step 4 must be green — that is the proof the fix works end-to-end. A passing service test alone is NOT sufficient.
• UI changes (any template file created or modified): in addition to the above, spawn the ui-review subagent on the screenshot folder from the Playwright run. Provide the expected user flow so it knows what to check. Fix any issues it reports before proceeding. If you modified a template file, it IS a UI change — do not classify it as "backend-only".

8. Beautify (UI changes only)

If the change introduced new UI elements:

Use /frontend (or apply the project's design system manually) to refine, then re-run Playwright tests and verify with ui-review subagent.

9. Commit

MANDATORY — commit your changes. Do not skip or defer this step.

Use /commit (or commit manually). Every TDD task ends with a commit.

Project Customization

Read references/project.md in this skill's directory if it exists. It provides project-specific context:

• Test base classes and when to use each
• Build, compile, and migration commands
• Package structure conventions
• Any other project-specific patterns