epic-template

# [Epic Name] – DESIGN

Status: Draft | In Progress | Completed
Target version: [x.y]

---

## 0. Scope & Non-Scope

### In Scope (initial release)

* [List what will be implemented in this epic]
* [Be specific about features, commands, behaviors]
* [Include technical components and user-facing features]

### Out of Scope (future work)

These features are explicitly outside of the initial release:

* [List what won't be done in this epic]
* [Helps prevent scope creep]
* [Can be considered for future epics]

---

## 1. Motivation & Goals

[Why is this epic needed? What problem does it solve?]

Design goals:

1. **[Goal 1]**
   [Description of what this goal means]

2. **[Goal 2]**
   [Description]

3. **[Goal 3]**
   [Description]

---

## 2. Terminology

* **[Term 1]** — [Definition]
* **[Term 2]** — [Definition]

---

## 3. [Component/Feature Name]

### 3.1 [Subsection]

[Detailed design information]

```[language if applicable]
[Code examples, schema definitions, etc.]
```

### 3.2 [Subsection]

[More details]

---

## 4. User-Facing Changes

### 4.1 New Features / Interfaces

[Describe new user-facing features, APIs, UI components, or endpoints]

Examples:
```
[Example usage or interaction]
```

### 4.2 Behavior Changes

[List any changes to existing behavior]

---

## 5. Implementation Notes

### 5.1 [Technical Area 1]

[Implementation guidance, constraints, technical decisions]

### 5.2 [Technical Area 2]

[More technical notes]

---

## 6. Error Handling & Edge Cases

### 6.1 [Error Case 1]

```
[Error message example]
```

### 6.2 [Edge Case 2]

[How to handle this case]

---

## 7. Testing Strategy

* [Test approach 1]
* [Test approach 2]
* [Key scenarios to test]