annotations/.cursor/skills/decompose/templates/feature-spec.md

Feature Specification Template

Create a focused behavioral specification that describes what the system should do, not how it should be built. Save as TASKS_DIR/<topic>/[##]_[component_name]/[##].[##]_feature_[feature_name].md.

---

# [Feature Name]

**Status**: Draft | **Date**: [YYYY-MM-DD] | **Feature**: [Brief Feature Description]
**Complexity**: [1|2|3|5] points
**Dependencies**: [List dependent features or "None"]
**Component**: [##]_[component_name]

## 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 feature

### 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] |

## Integration 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]

---

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 features

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
• Note dependencies on other features

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