---
doc_type: prd
domain: {{stable domain label from document-metadata-contract-v1.md}}
canonicality: canonical
owner: prd
status: draft
freshness_status: fresh
---

# {{Feature Name}} PRD

**Version**: 1.0
**Owner**: {{Owner}}
**Date**: {{YYYY-MM-DD}}
**Status**: Draft
**Feature ID**: {{FEAT-ID}}

---

## Canonical Sources

| Source | Document |
|--------|----------|
| Macro feature | {{macro feature name}} |
| Requirements owner | This PRD |
| Obsidian spec | {{[[Note Name]] — remove row if no Obsidian note was provided}} |
| Data model | {{link to ${paths.references_dir}/collections/...}} |
| API reference | {{link to ${paths.references_dir}/api/...}} |
| SSOT registry | {{link to ${paths.references_dir}/ssot-registry.md}} |

## Implementation References

| Reference | Path | Relevance |
|-----------|------|-----------|
| {{name}} | `{{file path}}` | {{why relevant}} |

## Backlog Links

Backlog cards to be created after PRD approval.

## Documentation Impact

| Document | Action |
|----------|--------|
| {{doc path}} | {{what to update}} |

## Design Reference & Mockup Inventory

> Omit this entire section only if UI impact is N/A. Otherwise include with
> `Mockup status: none` when the user did not provide mockups in Step 1.6.

**Mockup status:** {{provided | partial | none | n/a}}
**Step 3 mode:** {{full | hybrid | skipped}}
**Design entry point:** {{`${paths.prd_dir}/<slug>/design.html` | `${paths.prd_dir}/<slug>/mockups/` | both}}

### Screen inventory

| Schermata | User story | Mockup path | Origine | Note |
|-----------|------------|-------------|---------|------|
| {{Lista ordini}} | US-1 | `mockups/lista.png` | mockup utente | tokens align: ✅ |
| {{Onboarding}} | US-4 | `design.html#onboarding` | generato Step 3b | option scelta: B |

### Mapping schermata → componenti registry

> Populate only when `features.has_design_system: true`. Otherwise remove this
> subsection.

| Schermata | Componenti riusati | Componenti nuovi | Token violations |
|-----------|---------------------|------------------|------------------|
| {{Lista ordini}} | DataTable, Pagination | — | — |
| {{Dettaglio ordine}} | Card, StatusBadge | OrderTimeline (nuovo — vedi spec) | shadow `0 2px 8px` → `--shadow-card-elevated` |

### Source files originali

Per i mockup forniti come path locali, riportare il percorso utente pre-copia
(traceability). Per immagini in chat, scrivere `chat://image-N`.

- `{{~/Desktop/orders-mockup.png}}` → `mockups/orders-mockup.png`
- `chat://image-1` → analizzata inline, non copiata su disco

---

## 1. Problem Statement

{{Problem description with business impact.}}

### Ratio Strategica

#### Perché adesso, perché questo
{{Quale evento di business, segnale di mercato o priorità strategica rende questa feature necessaria in questo momento.}}

#### Segnale cliente / mercato
{{Feedback specifici dei clienti, dati d'uso, pressione competitiva o trend di mercato che hanno innescato questa iniziativa. Includere dati dove disponibili.}}

#### Impatto di business atteso
{{Risultati misurabili attesi: ricavi, retention, efficienza operativa, riduzione rischio. Quantificare dove possibile.}}

#### Allineamento strategico
{{Come questa feature si inserisce nella visione del prodotto e nelle priorità della roadmap attuale.}}

#### Alternative considerate
| Alternativa | Perché scartata |
|-------------|-----------------|
| {{opzione}} | {{motivo}} |

---

## 2. Goals and Non-Goals

### Goals

- **G1**: {{goal}}

### Non-Goals

- **NG1**: {{non-goal}}

---

## 3. Personas

### {{Persona 1}}

{{Description and context.}}

---

## 4. User Stories

- **US-1**: As a {{persona}}, I want to {{action}} so that {{benefit}}.

---

## 5. Data Model

{{Type definitions (TypeScript interfaces / Python dataclasses / SQL schema /
schema validators), persistence-layer schema changes, validation rules.}}

### Database Indexes & Query Optimization

> **Stack-specific variant** — populate the variant matching `stack.database`
> from `baldart.config.yml`. Remove the variants that do not apply. If
> `stack.database: ""` (unset), the PRD writer SHOULD ask the user which
> database is in use before completing this section.

**Variant A — Firestore** (`stack.database: firestore`)

Every query that combines `where()` on one field with `orderBy()` on a different
field, or multiple `where()` on different fields, REQUIRES a composite index.
Missing indexes cause runtime `FAILED_PRECONDITION` errors (500s in production).

| # | Collection | Fields | Order | Query Location | Status |
|---|-----------|--------|-------|----------------|--------|
| IDX-1 | `{{collection}}` | `{{field1}}` ASC, `{{field2}}` DESC | {{ASC/DESC}} | `{{file:function}}` | NEW / EXISTS |

Rules: every endpoint that reads with compound queries MUST list its indexes
here; `firestore.indexes.json` MUST be updated in the same commit; if no
compound queries: "Nessun indice composito richiesto".

**Variant B — Relational (Postgres / Supabase / MySQL / SQLite)**

| # | Table | Columns | Type | Used by | Migration |
|---|-------|---------|------|---------|-----------|
| IDX-1 | `{{table}}` | `{{col1}}, {{col2}}` | B-tree / GIN / partial | `{{query location}}` | `{{migration file}}` |

Rules: indexes ship in the same migration as the query; for Supabase, RLS
policies live alongside in `### Row-Level Security` below; queries on >100k
rows without a matching index → CRITICAL finding in api-perf-gate.

**Variant C — MongoDB**

| # | Collection | Fields | Type | Used by | Notes |
|---|-----------|--------|------|---------|-------|
| IDX-1 | `{{collection}}` | `{{field1}}: 1, {{field2}}: -1}` | compound / text / 2dsphere | `{{aggregation pipeline}}` | TTL / partial / sparse if applicable |

**Variant D — DynamoDB**

| # | Table | PK / SK | GSI / LSI | Access Pattern | Notes |
|---|-------|---------|-----------|----------------|-------|
| GSI-1 | `{{table}}` | `{{pk}} / {{sk}}` | GSI: {{name}} on {{attrs}} | {{query pattern}} | provisioned / on-demand |

**Variant E — None / no DB / N/A**

State explicitly: "Feature is stateless / does not touch the persistence layer".

---

## 6. API Contract Changes

{{Endpoints, request/response formats, validation.}}

---

## 7. UI Specifications

> Canonical visual reference: **Design Reference & Mockup Inventory** section above.
> This section describes specs that are NOT obvious from the mockups themselves
> (behavioral, responsive breakpoints, a11y, motion, copy variants by locale).
> Do NOT duplicate the screen list or component table — link to them above.

{{Layout details not visible in mockups, responsive behavior, a11y, motion, copy variants.}}

---

## 8. i18n Specification

{{Dictionary keys, locale files, provider patterns.}}

---

## 9. Acceptance Criteria

### {{Area}}

- **AC-1**: {{testable criterion}}

---

## 10. Edge Cases and Failure Modes

| Scenario | Expected Behavior |
|----------|-------------------|
| {{scenario}} | {{behavior}} |

---

## 11. Out of Scope

1. {{excluded item}}

---

## 12. Dependencies

| Dependency | Type | Status |
|------------|------|--------|
| {{dependency}} | {{type}} | {{status}} |

---

## 13. Test Plan

### E2E Evaluation

| Criterion | Result |
|-----------|--------|
| Has UI impact? | {{yes/no}} |
| Multi-step flow? | {{yes/no}} |
| Critical path? (auth/payment/booking) | {{yes/no}} |
| UI acceptance criteria count | {{N}} |
| **Verdict** | **{{NOT NEEDED / RECOMMENDED / REQUIRED}}** |
| Rationale | {{reason}} |

### Test Scenarios

{{If E2E NOT NEEDED: "Nessun test E2E pianificato — [rationale]"}}

{{If E2E REQUIRED or RECOMMENDED:}}

| # | Scenario | User Story | Acceptance Criteria | Priority |
|---|----------|------------|---------------------|----------|
| TS-1 | {{scenario description}} | US-{{N}} | AC-{{N}} | {{HIGH/MEDIUM}} |

### Test Credentials

> Personas drawn from `identity.audience_segments[]`. Credential values come
> from `.baldart/overlays/prd.md § Test Credentials` (preferred), or were asked
> to the user during discovery. **Do NOT paste real secrets here** — use
> references to a secret manager / `.env.test` / 1Password item.

| Persona | Auth Method | Credentials Reference | Notes |
|---------|-------------|-----------------------|-------|
| {{audience_segments[0]}} | {{OTP / password / magic link / token}} | {{secret-manager://path or .env.test:VAR}} | {{notes about context, tenant, store, etc.}} |

### Test Data Prerequisites

{{Any data that must exist in the datastore before tests can run (e.g., seed records, config rows, fixture entities).}}

---

## 14. Pipeline Touchpoints (Implementation Summary)

| Step | File | Change |
|------|------|--------|
| 1 | `{{file}}` | {{change}} |

---

## 15. Integration Surface Map (ISA)

Existing code that must reference, link to, or interact with this feature.
Every ISA entry MUST be covered by at least one backlog card.

| # | Category | Existing File | Action Required | Risk if Omitted | Card |
|---|----------|--------------|-----------------|-----------------|------|
| ISA-1 | {{NAVIGATION / PERMISSIONS / SETTINGS / SEARCH / NOTIFICATIONS / DASHBOARD / API_CONSUMERS / SHARED_STATE}} | `{{file path}}` | {{what to do}} | {{consequence}} | {{FEAT-ID or TBD}} |

**Risk summary:** HIGH: {{N}} | MEDIUM: {{N}} | LOW: {{N}}

### ISA Traceability Matrix

| ISA # | Touchpoint | Card(s) | Status |
|-------|-----------|---------|--------|
| ISA-1 | {{touchpoint}} | {{FEAT-ID}} | Covered / Missing |

**Every ISA entry MUST map to at least one card. Missing entries = incomplete plan.**
