# Design Doc: [TITLE]
<!-- Purpose: Capture the reasoning behind a significant change BEFORE building it.
     AI agents can reference this doc to understand intent, constraints, and
     rejected alternatives. Check this into the repo alongside the code.

     Workflow:
       1. Author fills out this template
       2. Reviewers comment (in PR or directly)
       3. Approved doc is merged to docs/design/
       4. Implementation references this doc in PR descriptions
       5. Agent reads this doc for context when working in related areas
-->

## Metadata

| Field          | Value                                    |
|----------------|------------------------------------------|
| Author(s)      | [NAME(S)]                                |
| Status         | [Draft / In Review / Approved / Implemented / Superseded] |
| Created        | [YYYY-MM-DD]                             |
| Last Updated   | [YYYY-MM-DD]                             |
| Supersedes     | [LINK_TO_PREVIOUS_DOC or N/A]            |
| Superseded By  | [LINK_TO_NEWER_DOC or N/A]               |
| Related Issues | [LINK(S) to GitHub issues, Jira tickets] |

## Problem Statement

<!-- What problem are we solving? Why now? Who is affected?
     Be specific. Include data if available (error rates, user complaints, etc.) -->

[PROBLEM_DESCRIPTION]

## Goals & Non-Goals

### Goals
- [GOAL_1 -- e.g., "Reduce P99 invoice generation latency from 8s to under 1s"]
- [GOAL_2]
- [GOAL_3]

### Non-Goals
<!-- Explicitly state what this design does NOT try to solve. -->
- [NON_GOAL_1 -- e.g., "Migrating existing invoices to the new format"]
- [NON_GOAL_2]

## Background

<!-- Context the reader needs. Link to existing docs rather than repeating them. -->

[BACKGROUND_DESCRIPTION]

Key references:
- [LINK_1 -- e.g., "ARCHITECTURE.md -- current system design"]
- [LINK_2 -- e.g., "ADR-012 -- why we chose Azure SQL Database"]

## Proposed Solution

<!-- Describe the design. Use diagrams, code snippets, and examples. -->

### Overview

[SOLUTION_OVERVIEW]

### Detailed Design

[DETAILED_DESIGN -- Include API contracts, data models, sequence diagrams, etc.]

```
[CODE_SNIPPET or ASCII_DIAGRAM if helpful]
```

### Data Model Changes

<!-- If this changes the database schema, describe the changes. -->

[DATA_MODEL_CHANGES or "No data model changes required."]

### API Changes

<!-- If this changes public or internal APIs, describe the changes. -->

[API_CHANGES or "No API changes required."]

## Alternatives Considered

<!-- Document rejected approaches and WHY they were rejected.
     This is extremely valuable for agents -- it prevents them from
     re-proposing ideas that were already evaluated and dismissed. -->

### Alternative 1: [NAME]

[DESCRIPTION]

**Rejected because:** [REASON]

### Alternative 2: [NAME]

[DESCRIPTION]

**Rejected because:** [REASON]

## Risks & Mitigations

| Risk                           | Impact | Likelihood | Mitigation                    |
|--------------------------------|--------|------------|-------------------------------|
| [RISK_1 -- e.g., "Data loss during migration"] | High   | Low        | [MITIGATION]                  |
| [RISK_2]                       | [H/M/L] | [H/M/L]  | [MITIGATION]                  |

## Rollout Plan

<!-- How will this be deployed? Feature flags? Gradual rollout? -->

1. [STEP_1 -- e.g., "Deploy behind feature flag `new-invoice-engine`"]
2. [STEP_2 -- e.g., "Enable for internal team for 1 week"]
3. [STEP_3 -- e.g., "Enable for 10% of users, monitor error rates"]
4. [STEP_4 -- e.g., "Full rollout, remove feature flag"]

### Rollback Plan

[ROLLBACK_DESCRIPTION -- e.g., "Disable feature flag. Old code path remains
functional. No data migration needed for rollback."]

## Observability

<!-- How will you know this is working? What metrics/alerts are needed? -->

- [METRIC_1 -- e.g., "Dashboard: invoice generation P50/P95/P99 latency"]
- [METRIC_2 -- e.g., "Alert: invoice generation error rate > 1%"]
- [LOG -- e.g., "Structured log event: invoice.generated with duration_ms"]

## Testing Strategy

- [APPROACH_1 -- e.g., "Unit tests for the new generation engine"]
- [APPROACH_2 -- e.g., "Integration test comparing old vs new output for 1000 sample invoices"]
- [APPROACH_3 -- e.g., "Load test simulating 10x current peak traffic"]

## Open Questions

<!-- Unresolved questions that need discussion. Remove items as they are resolved. -->

- [ ] [QUESTION_1]
- [ ] [QUESTION_2]