tdd-task

---

name: tdd-task description: Implement a feature or fix a bug using TDD in this repository: write a failing test first, implement the smallest passing change, refactor, and verify with the relevant Maven and frontend commands. dependencies:

• design-postgres-tables
• frontend-design
• jooq-best-practices
• preact

---

TDD Task

Implement a feature or fix a bug by writing a failing test first, then making it pass.

Process

0. Plan

Before changing code, create a visible checklist with the available planning tool. Track these tasks and update each item as it starts and completes:

1. Understand: trace the relevant code paths and find the closest analog.
2. Clarify: ask targeted questions before coding when the answer changes the implementation.
3. Classify: choose the right test type and verification command.
4. Red: write a compiling test that fails for the intended reason.
5. Green: implement the smallest change that makes the test pass.
6. Refactor: simplify changed code while preserving behavior.
7. Verify: run the relevant backend and frontend checks.
8. Commit: commit only when the user explicitly asks for a commit.

Add project-specific sub-steps when needed, such as a database migration, jOOQ usage review, or browser verification.

1. Understand

Explore the codebase before writing tests:

• Search for existing implementations of the same concept.
• Read the nearest analog end-to-end, including controller, service, repository, component, and test coverage where present.
• Identify whether the change belongs in the Spring Boot backend, the Vite/Preact frontend, or both.
• Check whether an existing test class should be extended before creating a new one.
• For bugs, trace the broken behavior from entry point to failing branch.
• For library APIs, prefer local Javadocs or the javadoccentral MCP server when available.

2. Clarify

Ask targeted questions only when the answer changes what gets built. Keep questions concrete and limited.

Ask for clarification when there is meaningful ambiguity about:

• Scope, such as whether a related behavior is included.
• Behavior, such as competing plausible outcomes for the same input.
• Data modeling, such as schema shape or constraints.
• Existing data, such as whether a backfill is required.
• User roles or visible flows that need verification.
• Test boundaries, such as service test versus web MVC test versus browser test.

Do not ask about choices already answered by code conventions, naming style, or the fact that TDD should be used.

3. Classify

Pick the smallest useful automated test that proves the behavior:

• Pure Java logic: JUnit test without Spring context.
• Spring service, repository, jOOQ, Flyway, or database behavior: Spring Boot test with @Import(TestcontainersConfiguration.class) when PostgreSQL is needed.
• HTTP controller behavior: Spring Web MVC test when a focused slice is enough, or Spring Boot test when full wiring matters.
• Preact component or frontend logic: add or use a frontend test runner if one exists; otherwise add the missing test harness when the task requires test-driven frontend behavior.
• User-observable browser behavior: add an E2E/browser test when the repo has a harness, or explicitly add the harness as part of the task before relying on browser-only verification.

Use manual browser inspection only as extra verification, not as the Red step, unless the user explicitly approves a task without automated browser coverage.

4. Red

Do not write implementation code until the Red step is complete.

The test must compile, run, and fail because the current behavior is wrong. A compile error is not a valid Red result.

For backend tests:

1. Create any minimal stub needed for compilation.
2. Write assertions for the intended behavior.
3. Run the narrow Maven test command from references/project.md.
4. Confirm the failure is an assertion or expected behavioral failure.

For frontend tests:

1. Add the test harness first when none exists and the task requires frontend TDD.
2. Write the failing test against the component, state transition, or browser-visible behavior.
3. Run the narrow frontend test command if configured.
4. Confirm the failure demonstrates the missing behavior.

If a database schema change is needed, add a Flyway migration before writing tests that depend on the schema.

5. Green

Write the smallest implementation that makes the failing test pass.

• Keep changes close to the code path under test.
• Prefer existing package structure and framework patterns.
• For jOOQ queries, use the jooq-best-practices skill.
• For PostgreSQL table design, use the design-postgres-tables skill.
• For Preact code, use the preact skill.

Run the narrow test command until the Red test is green.

6. Refactor

Review changed code for clarity, duplication, naming, and fit with local patterns.

Refactor only when it improves the changed area. Avoid unrelated cleanup.

Run the narrow test command again after refactoring.

7. Verify

Run the commands that match the changed surface:

• Backend Java/Spring changes: targeted Maven test, then broader Maven test when risk justifies it.
• Database changes: targeted Spring Boot/Testcontainers test that exercises the migration-dependent behavior.
• Frontend changes: npm run build from frontend/; run configured tests when present.
• UI changes: inspect the affected screen in a browser when practical, especially after layout or interaction changes.

Record which commands passed and which could not be run.

8. Commit

Commit only when the user asks for a commit.

Before committing:

• Check git status --short.
• Stage only files belonging to the completed task.
• Do not include unrelated user changes.
• Use a concise message that names the behavior changed.

Project Customization

Read references/project.md in this skill directory before running commands. It describes the supported commands, test patterns, and current repository layout.