# Task Specification Template

Create a focused behavioral specification that describes **what** the system should do, not **how** it should be built.
Save as `TASKS_DIR/[##]_[short_name].md` initially, then rename to `TASKS_DIR/[TRACKER-ID]_[short_name].md` after work item ticket creation.

---

```markdown
# [Feature Name]

**Task**: [TRACKER-ID]_[short_name]
**Name**: [short human name]
**Description**: [one-line description of what this task delivers]
**Complexity**: [1|2|3|5] points
**Dependencies**: [AZ-43_shared_models, AZ-44_db_migrations] or "None"
**Component**: [component name for context]
**Tracker**: [TASK-ID]
**Epic**: [EPIC-ID]

## Problem

Clear, concise statement of the problem users are facing.

## Outcome

- Measurable or observable goal 1
- Measurable or observable goal 2
- ...

## Scope

### Included
- What's in scope for this task

### Excluded
- Explicitly what's NOT in scope

## Acceptance Criteria

**AC-1: [Title]**
Given [precondition]
When [action]
Then [expected result]

**AC-2: [Title]**
Given [precondition]
When [action]
Then [expected result]

## Non-Functional Requirements

**Performance**
- [requirement if relevant]

**Compatibility**
- [requirement if relevant]

**Reliability**
- [requirement if relevant]

## Unit Tests

| AC Ref | What to Test | Required Outcome |
|--------|-------------|-----------------|
| AC-1 | [test subject] | [expected result] |

## Blackbox Tests

| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|------------------------|-------------|-------------------|----------------|
| AC-1 | [setup] | [test subject] | [expected behavior] | [NFR if any] |

## Constraints

- [Architectural pattern constraint if critical]
- [Technical limitation]
- [Integration requirement]

## Risks & Mitigation

**Risk 1: [Title]**
- *Risk*: [Description]
- *Mitigation*: [Approach]

## Contract

<!--
OMIT this section for behavioral-only tasks.
INCLUDE this section ONLY for shared-models / shared-API / contract tasks.
See decompose/SKILL.md Step 2 shared-models rule and decompose/templates/api-contract.md.
-->

This task produces/implements the contract at `_docs/02_document/contracts/<component>/<name>.md`.
Consumers MUST read that file — not this task spec — to discover the interface.
```

---

## Complexity Points Guide

- 1 point: Trivial, self-contained, no dependencies
- 2 points: Non-trivial, low complexity, minimal coordination
- 3 points: Multi-step, moderate complexity, potential alignment needed
- 5 points: Difficult, interconnected logic, medium-high risk
- 8+ points: Too complex — split into smaller tasks

## Output Guidelines

**DO:**
- Focus on behavior and user experience
- Use clear, simple language
- Keep acceptance criteria testable (Gherkin format)
- Include realistic scope boundaries
- Write from the user's perspective
- Include complexity estimation
- Reference dependencies by tracker ID (e.g., AZ-43_shared_models)

**DON'T:**
- Include implementation details (file paths, classes, methods)
- Prescribe technical solutions or libraries
- Add architectural diagrams or code examples
- Specify exact API endpoints or data structures
- Include step-by-step implementation instructions
- Add "how to build" guidance
