# Feature Specification: {{titleCase FEATURE_NAME}}

| Field | Value |
|-------|-------|
| **ID** | {{FEATURE_NAME}} |
| **Status** | Draft / In Review / Approved / In Progress / Done |
| **Created** | {{DATE}} |
| **Stack** | {{STACK}} |
| **Complexity** | Low / Medium / High |
| **Estimated Cost** | $X/month |
| **Agents** | Core: All / Specialists: {list} |

---

## Overview

**Problem:** {What problem this feature solves}

**Solution:** {High-level solution}

**Success Criteria:**
- [ ] {Criterion 1}
- [ ] {Criterion 2}

---

## Requirements

**Functional:** FR1: {desc} | FR2: {desc} | FR3: {desc}

**Non-Functional:** NFR1: Performance - {target} | NFR2: Reliability - {target}

---

## User Stories

### US001: {Title}
**As** {user type} **I want** {feature} **so that** {benefit}

**Acceptance Criteria:** 1. {criterion} 2. {criterion}

**Edge Cases:** {edge case}: {handling}

---

## Technical Architecture

### Stack
| Component | Technology |
|-----------|------------|
| Frontend | {Next.js / .NET 10} |
| Backend | .NET 10 / C# 14 |
| Database | {Azure SQL / Cosmos DB} |

### Data Model

#### {EntityName}
| Column | Type | Constraints |
|--------|------|-------------|
| Id | Guid | PK |
| {Property} | {Type} | {Constraints} |
| CreatedAt | datetime2 | Default: GETUTCDATE() |

### Contracts

```csharp
public interface I{{pascalCase FEATURE_NAME}}Service
{
    Task<{{pascalCase FEATURE_NAME}}Dto> GetByIdAsync(int id);
    Task<{{pascalCase FEATURE_NAME}}Dto> CreateAsync(Create{{pascalCase FEATURE_NAME}}Request request);
}
```

**Contracts Workflow:** Generate `contracts.cs` FIRST → validate names → reference in spec → approve with user.

**Validation Checklist:**
- [ ] Property names are descriptive (not generic "Data", "Value")
- [ ] Records use correct types (Stream vs byte[], Guid vs string)
- [ ] Response DTOs have all properties needed for UI
- [ ] Request DTOs have implicit validations (required, nullable)

---

## Domain Complexity

**Nível:** {1 — CRUD / 2 — Business Logic / 3 — Bounded Context}

**Justificativa:** {Por que este nível foi escolhido — mencionar invariants, eventos ou BCs se Nível 2+}

**Padrões Aplicados:**
- {Nível 1: Entity simples, Service CRUD, DTOs}
- {Nível 2: AggregateRoot, Value Objects, Domain Events, CQRS}
- {Nível 3: Bounded Context isolation, cross-BC events, Linguagem Ubíqua}

**Padrões Omitidos:**
- {ex: Bounded Contexts — sistema single-domain}

---

## Architecture Style: Vertical Slice

> Preencher SOMENTE se `config.architecture.style === "vertical-slice"`. Omitir em projetos DDD.

**Architecture Style:** Vertical Slice Architecture (VSA)

**Entity Fields:**
| Field | Type | Constraints |
|-------|------|-------------|
| Id | Guid | PK, `Guid.CreateVersion7()` |
| {Field} | {C# Type} | {Required / Optional / Unique} |
| CreatedAt | DateTimeOffset | Auto |

**Operations:**
| Slice | HTTP | Route | Has Validator |
|-------|------|-------|---------------|
| Create{Entity} | POST | {ROUTE} | Yes |
| GetAll{Entity}s | GET | {ROUTE} | No |
| Get{Entity}ById | GET | {ROUTE}/{id} | Yes |
| Update{Entity} | PUT | {ROUTE}/{id} | Yes |
| Delete{Entity} | DELETE | {ROUTE}/{id} | Yes |

**Error Types ({Entity}Errors):**
- `{Entity}Errors.{ErrorName}()` — {description}

**Validation Rules:**
| Field | Rules |
|-------|-------|
| {Field} | NotEmpty(), MaxLength({N}), {etc.} |

---

## Aggregate Blueprint (Nível 2+ apenas)

> Omitir esta seção se Nível 1 (CRUD) ou se Architecture Style = Vertical Slice.

### Aggregate Root: {EntityName}

**Invariants:**
- {Invariant 1 em linguagem natural}
- {Invariant 2}

**Estados e Transições:**
```
{Status.Draft} → Confirm() → {Status.Confirmed} → Cancel() → {Status.Cancelled}
```

**Domain Events:**
- `{EntityName}CreatedEvent` — publicado ao criar
- `{EntityName}StatusChangedEvent` — publicado em mudança de estado

**Value Objects:**
- `{ValueObjectName}` — {por que não é primitivo simples}

**Referências Cross-Aggregate (por ID):**
- `{OtherEntity}Id: Guid`

### Linguagem Ubíqua

| Termo | Definição | Código |
|-------|-----------|--------|
| {Termo} | {Definição do negócio} | `{ClassName.MethodName()}` |

---

## UI/UX Design (if front-end)

### Wireframes
```
{ASCII wireframe per screen - include states: loading, error, empty}
```

### User Flow
1. {Step} → {System response}

---

## Flows

### {Flow Name}
**Trigger:** {what starts this flow}
1. {Actor} {action} → {system response}
2. If {condition}: Path A / Else: Path B
**End State:** {final state}

---

## Cost Estimate

| Resource | SKU | Monthly Cost | Justification |
|----------|-----|--------------|---------------|
| {Resource} | {SKU} | ${X} | {Why} |
| **Total** | | **${X}/month** | |

---

## ADRs (Architectural Decision Records)

### ADR-001: {Decision Title}
**Status:** Proposed / Accepted
**Context:** {Why decide now}
**Decision:** {What we chose}
**Alternatives:** 1. {Alt} (pros/cons) 2. {Alt} (pros/cons)
**Trade-offs:** {key trade-offs}

---

## Security

| Action | Required Policy |
|--------|-----------------|
| View | CanView{Feature} |
| Create | CanManage{Feature} |

## Risks

| Risk | Impact | Mitigation |
|------|--------|------------|
| {Risk} | {H/M/L} | {Mitigation} |

## Out of Scope
- {Item}

## Definition of Done
- [ ] Code implemented
- [ ] Tests >80% coverage
- [ ] Code review approved
- [ ] Deploy to staging
- [ ] Recap.md generated