Feature Specification Template

# Feature Spec: [Feature Name]

## Overview

One paragraph describing the feature, its purpose, and how it fits
into the larger product.

## User Stories

- As a [user type], I want to [action], so that [outcome].
- As a [user type], I want to [action], so that [outcome].

## Detailed Behavior

### [Sub-feature 1, e.g., "Customer login"]

**Inputs:**
- Field 1 (type, validation rules).
- Field 2 (type, validation rules).

**Outputs:**
- Success: [what the user sees, what gets stored, what events fire].
- Failure: [error states and what each looks like].

**Rules:**
- Rule 1.
- Rule 2.

**Edge cases:**
- Empty input: ...
- Malformed input: ...
- Duplicate submission: ...
- Permission denied: ...

**Error handling:**
- User-facing error: [message text].
- Logged: [what gets logged].
- Notified: [who, if anyone, gets notified].

### [Sub-feature 2]

(Repeat the structure above.)

## Data Model

### Tables touched

- `table_name`: read [columns], written [columns].

### New tables required

```sql
CREATE TABLE example (
    id SERIAL PRIMARY KEY,
    field_1 TEXT NOT NULL,
    field_2 INTEGER,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

Permissions

• Role X: can [actions].
• Role Y: can [actions].
• Role Z: cannot access this feature at all.

API Endpoints

(If this feature exposes API endpoints, list them with the format from section 5.6.)

UI Notes

• Layout: [reference to the layout from section 5.2].
• Components: [reference to components from section 5.3].
• Design tokens: see design-tokens.md.

Verification Checklist

• Happy path 1: ...
• Happy path 2: ...
• Edge case 1: ...
• Edge case 2: ...
• Failure mode: ...

AFD Check

Per §1.4: is any part of this feature AFD? If yes, name the human expert reviewing it: ____________

Out of Scope (this feature)

• ...