# Task Generation Rules

## Core Principles

### 1. Describe Capabilities, Not Code Structure
Task descriptions communicate what the system must be able to do — they do not prescribe file names, function signatures, or class hierarchies. Those decisions belong in `design.md` and are made by the implementer.

**Write about**:
- What functionality the user or system gains
- What business behavior or domain rule is being enforced
- What data relationships are being established
- What integration or workflow is being wired together

**Do not write about**:
- Which file or directory the code goes in
- What function or method name to use
- What type or interface name to define
- Which data structure to instantiate internally

**Why this matters**: Implementation details in task descriptions create conflicts with `design.md` and constrain the implementer unnecessarily. Tasks describe the work; design describes the contracts.

### 2. Every Task Connects to the System
No task should produce code that floats unconnected from the rest of the system. Every task must:
- Build on the output of earlier tasks or on existing system foundations
- Deliver functionality that is immediately usable or testable within the system
- Advance the build incrementally — no large jumps in complexity between consecutive tasks
- Validate core functionality early in the sequence rather than at the end
- Respect the architecture boundaries defined in `design.md`
- Honor the interface contracts documented in `design.md`

Container-only major tasks — those whose description is fully captured by their sub-tasks — should have a concise summary label and no redundant detail bullets.

End the task list with integration tasks that wire all components together and confirm end-to-end behavior.

### 3. Size Tasks for Focused Execution
**Major tasks**: Group logically cohesive sub-tasks — let natural coherence determine the grouping, not an arbitrary count.

**Sub-tasks**: Target 1–3 hours of implementation work each. Include 3–10 detail bullets per sub-task to guide the implementer without over-constraining.

Avoid both extremes: tasks so small they create tracking noise, and tasks so large they become uncertain in scope.

### 4. Map Every Task to Its Requirements
At the end of each sub-task's detail bullets, include:

```
_Requirements: X.X, Y.Y_
```

Rules for requirement references:
- List only numeric IDs, comma-separated (e.g., `1.1, 2.3, 3.1`)
- Never append descriptions, translations, parenthetical notes, or labels
- For cross-cutting requirements, list every applicable ID — not just the primary one
- All requirements in `requirements.md` must have numeric IDs; stop and fix the document if any are missing before generating tasks
- Optionally add `_Contracts: ServiceName API_` when a specific interface from `design.md` is central to the task

### 5. Code-Only Task Scope
Tasks cover work that results in committed, tested code. Exclude:

- Deployment and release procedures
- Documentation writing tasks
- User acceptance testing or manual QA activities
- Business or marketing activities

**Include**: implementation coding, unit tests, integration tests, end-to-end tests, and infrastructure or configuration tasks required to run the code.

### Optional Test Coverage Tasks
When the design and core implementation already ensure functional coverage, and MVP delivery speed is prioritized, purely supplementary test work (e.g., baseline rendering tests, snapshot coverage) may be marked optional:

- Use the `- [ ]*` checkbox form
- Apply only to sub-tasks that reference specific acceptance criteria already satisfied by core implementation
- Never apply to implementation work, integration verification, or tests that are required for a correct system — those are mandatory

---

## Task Hierarchy Rules

### Depth Limit: Two Levels Only
- **Level 1 — Major Tasks**: Numbered 1, 2, 3, 4... describing a cohesive area of work
- **Level 2 — Sub-Tasks**: Numbered 1.1, 1.2, 2.1, 2.2... within their parent major task
- No sub-sub-tasks (1.1.1 or deeper)

**Collapsing single-sub-task structures**: If a major task would contain exactly one actionable sub-task, promote the sub-task to the major task level and remove the nesting. Unnecessary hierarchy creates confusion.

### Sequential Numbering is Mandatory
- Major task numbers must increment monotonically: 1, 2, 3, 4, 5...
- Sub-task numbers reset per major task: 1.1, 1.2 then 2.1, 2.2 — never continue from one major task to another
- A major task number must never be repeated anywhere in the document

### Parallel Identification (Default Mode)
Unless `--sequential` mode is requested, identify and mark tasks that can execute concurrently.

Append `(P)` immediately after the task number for any task that satisfies all of the following:
- No data dependency on another pending task
- No conflicting writes to shared files or mutable resources
- No required review or approval from another task
- Any environment or setup needs are already satisfied or self-contained within this task

Mark `(P)` at both major task and sub-task levels when appropriate. Skip `(P)` on container-only major tasks — evaluate parallelism at the sub-task level instead.

In `--sequential` mode, omit all `(P)` markers.

### Checkbox Format Reference
```markdown
- [ ] 1. Major task summary
- [ ] 1.1 Sub-task description
  - Detail: what this sub-task accomplishes
  - Detail: edge case or constraint to handle
  - Detail: integration point or validation requirement
  - _Requirements: 1.1, 1.3_

- [ ] 1.2 Sub-task description
  - Detail items...
  - _Requirements: 2.1_

- [ ] 2. Next major task (must be 2, not 1 again)
- [ ] 2.1 (P) Sub-task that can run in parallel
  - Detail items...
  - _Requirements: 3.1, 3.2_
```

---

## Requirements Coverage Verification

Before finalizing the task list, cross-reference every requirement ID from `requirements.md` against the task list:
- Every ID must appear in at least one `_Requirements:` annotation
- Every top-level requirement must have at least one task that addresses it
- If a gap is found: return to the requirements or design phase to resolve it — do not silently skip requirements

If a requirement is intentionally deferred (e.g., post-MVP scope), document the deferral explicitly in the task list with a brief rationale.

Use `N.M`-style IDs where `N` is the top-level requirement number from `requirements.md` and `M` is the sub-item index within that requirement group.
