spring-task-decomposition

Spring task decomposition

Sizing rule

Each task is 1–4 hours for a competent engineer. If larger, split. If smaller than 30 minutes, fold into the previous task.

Shape

A good task has all of:

1. Stable ID T-NNN. Never renumber.
2. Linked AC-IDs — what user-visible criteria this task moves forward.
3. Test-IDs — at least one (T-NNN-T1, T-NNN-T2).
4. Files in scope — every path the task is allowed to edit (production + tests). The hook enforces this.
5. Dependencies — T-NNN IDs that must be done first.
6. Gates — which harness layers run for this task (default: all that touch the changed packages).
7. Rollback — one sentence on how to revert if validation fails.

Layering convention

Order tasks so that dependencies flow inward:

1. Domain & contracts — DTOs, value objects, OpenAPI snippet, migration script.
2. Unit / slice tests + minimum impl — one task per controller / service / repository concern.
3. Integration tests — Testcontainers, end-to-end through the controller.
4. Cross-cutting — ArchUnit rules, error envelope, observability.

Worked example (excerpt from 04-tasks.md)

### T-001 — Add `apply-gift-card` request DTO and validation
- **AC-IDs:** AC-001, AC-003
- **Test-IDs:** T-001-T1 (rejects blank code), T-001-T2 (rejects negative total)
- **Files in scope:**
  - `src/main/java/com/example/shop/checkout/ApplyGiftCardRequest.java`
  - `src/test/java/com/example/shop/checkout/ApplyGiftCardRequestTest.java`
- **Dependencies:** none
- **Gates:** format, compile, unit
- **Rollback:** delete the two files; nothing else references them yet.

### T-002 — `POST /checkout/{orderId}/gift-card` controller stub
- **AC-IDs:** AC-001, AC-002, AC-003
- **Test-IDs:** T-002-T1 (404 when order missing), T-002-T2 (415 when wrong content-type), T-002-T3 (returns 200 happy-path with stub service)
- **Files in scope:** controller class + `@WebMvcTest`
- **Dependencies:** T-001
- **Gates:** format, compile, unit, slice