michaeldyrynda/dotfiles/to-spec

# {Title}
 
## Overview
 
2-3 sentences on what this work achieves and why.
 
## User Jobs / Product Surfaces
 
This section is **required**. It defines the vertical slices the task planner will decompose into. Each entry is a real thing a real person does — not a technical layer.
 
For each user job:
 
| Field | Description |
|-------|-------------|
| **Role** | Who does this (e.g. "Customer", "Support agent", "Admin", "API consumer") |
| **Goal** | What they are trying to accomplish, in their words |
| **Entry point** | Where they start (URL, admin panel, CLI command, email link) |
| **Completion state** | What "done" looks like from their perspective |
| **Product surface** | The UI or interface where this happens (admin page, public form, email, API) |
| **Depends on** | Other user jobs that must be buildable first (use sparingly) |
 
Example entries:
 
-**Customer reviews an order:** Role: Customer. Goal: See order status and line items after purchase. Entry point: email link → `/orders/{reference}`. Completion state: order page renders current status, totals, and delivery details. Surface: public account page. Depends on: none (first slice).
-**Support agent refunds a payment:** Role: Support agent. Goal: Resolve a customer refund request. Entry point: admin order detail page. Completion state: refund is recorded, customer is notified, and the order timeline shows the action. Surface: admin workflow. Depends on: "Customer reviews an order" if it needs the same order model.
-**API consumer creates a project:** Role: API consumer. Goal: Create a project through the public API. Entry point: `POST /api/projects`. Completion state: response returns the created project and it is visible through `GET /api/projects/{id}`. Surface: API endpoint. Depends on: authentication foundation if not already present.
 
Group related jobs under a product surface heading if helpful. The task planner will use these entries — not the technical sections below — as the primary axis for slicing work.
 
## Payload Shape / API Contract / Interface
 
Concrete examples: JSON payloads, function signatures, CLI usage, schema definitions. Whatever makes the contract unambiguous.
 
### Field definitions
 
Table of fields with type, required/optional, and description.
 
## Domain Model / Enum / Config
 
New types, enums, config keys, or constants introduced by this work. Include the mapping to existing domain concepts where relevant.
 
## Validation Rules
 
Validation logic, constraints, after-validation hooks. Reference existing validators if extending them.
 
## Behaviour
 
Step-by-step description of what the implementation does at runtime. Name the action/service classes, their signatures, and the order of operations.
 
### Design constraints
 
Invariants, things deliberately excluded, entry-point agnosticism, idempotency guarantees.
 
Always include:
-**TDD is mandatory.** Red-green-refactor, strictly one test at a time. Never write all tests then implement.
 
## Testing
 
| Decision | Choice | Rationale |
|----------|--------|-----------|
| Testing | Strict TDD red-green-refactor | One test at a time, green before next. Never write all tests then implement. |
 
Specify test file locations and the kinds of tests expected (unit, feature, integration). If particular assertions or scenarios are known, list them — the task planner will promote each into its own acceptance criteria bullet, and the implementor will use each as a single red-green-refactor cycle.
 
## Edge Cases
 
Bullet list of edge cases and how each is handled.
 
## Files to Create/Modify
 
### New files
-Path — one-line description
 
### Modified files
-Path — what changes