<!-- Technical specification template from https://spec-coding.dev/blog/how-to-write-technical-spec-template-guide
     Core sections are required for every spec. Keep the design sections that apply and delete the rest. -->

# Feature: [Short, descriptive feature name]

## Goal
[1-3 sentences. What user problem or business outcome does this solve?
Write it so someone can look at the finished feature and say
"yes, this achieves the goal" or "no, it doesn't."]

## Non-goals (this version)
- [What this feature explicitly will NOT do]
- [Scope boundary that prevents drift]
- [Adjacent feature that is out of scope and why]

## Acceptance Criteria

Given [precondition: a specific system state or user context]
When [trigger: a specific action the user or system takes]
Then [outcome: the observable, testable result]

Given [precondition]
When [trigger]
Then [outcome]

[Add as many criteria as needed. Each one should be independently
testable by QA without asking the author for clarification.]

## Edge Cases

- [Input condition or system state that the main criteria don't cover]
  Resolution: [What the system does in this case]

- [Empty input / null value / concurrent write / permission boundary]
  Resolution: [Expected behavior]

## Output / Deliverables
1. [Concrete artifact: API endpoint, database migration, module, etc.]
2. [Feature flag name and default value]

## Dependencies
- [Service, team, or system that must exist before implementation]
  Owner: [team name]. Status: [available / ETA]

---- Design sections: keep the ones that apply, delete the rest ----

## Background
[What exists today and why it needs to change. Link the PRD or
ticket instead of restating it.]

## Proposed Design
[Components that change and how they interact. One diagram or a
short numbered flow is usually enough.]

## API / Interface Changes
[Endpoint or event, request and response shapes, status and error
codes, backward compatibility for existing clients.]

## Data Model and Migration
[New or changed tables and fields. Migration phases, backfill, and
the point after which rollback is no longer a config change.]

## Non-functional Requirements
[p95 latency, throughput, availability, rate limits, cost. Numbers,
not adjectives.]

## Security and Privacy
[Who can call or see this. Personal data stored, logged, or exported.]

## Alternatives Considered
[Option, and why it was rejected. One or two lines each.]

## Test Plan
[Which test proves each acceptance criterion: unit, integration,
end-to-end, or manual.]

## Rollout Plan
Stage 1: [Limited rollout: internal or percentage-based]
  Observation: [Duration]
  Success signal: [Metric or absence of failure]
  Stop condition: [Threshold that halts the rollout]

Stage 2: [Broader rollout]
  Observation: [Duration]
  Success signal: [Metric]

Rollback:
  Step 1: [Immediate reversal, e.g. feature flag off]
  Step 2: [Data repair if needed]

## Monitoring
[Metric or log line, alert threshold, and who is paged.]

## Open Questions
[Question, owner, decide-by date. Empty before implementation starts.]