design

Design

Settle choices that implementation must not invent. A useful design states the behavior, the main tradeoff, and the proof before code is written.

Process

1. Read the request, repository instructions, relevant code, and linked material.
2. Identify choices that would change behavior, interfaces, data, errors, security, operations, or tests.
3. Ask blocking questions before drafting. Ask only when the answer would change the design, and recommend an answer. Record non-blocking questions and a recommended default under Open questions.
4. Write docs/<feature-slug>/design.md using the numbered shape below. Keep it short and in order. Omit only sections that do not apply.
5. Run the review pass. Fix what you can. List the rest under Open questions.
6. Stop with the proposed design ready for review. Do not plan or implement it.

Document shape

# <Title>

> **Status:** Proposed for review

## 1. Executive summary
Say what is wrong today, who feels the problem, what will change, how we plan to fix it, and the main downside. Use simple words. Do not list sections or implementation details.

## 2. Context and scope
Describe the current behavior, why it is insufficient, what changes once this ships, and the boundary of this design.

## 3. System context
Show where the change fits in the current system. Name the parts and outside systems it touches and the boundaries it must preserve. Include a small diagram when it makes those relationships clearer.

## 4. Proposed design

### How it works
Walk one real case from start to finish. Name the thing that arrives, what handles it, what gets written down, and what the user sees.

### Components and responsibilities
For each changed part, state what it owns, what it depends on, and what it does not own.

### Decisions
For each real choice, say what you chose, what you rejected, and what the choice costs. Use one short paragraph. Skip choices nobody would question.

## 5. Invariants and requirements

### Invariants
List rules that must always hold as `INV-1`, `INV-2`, and so on. A reviewer checks the code against these rules, so keep them short and testable.

### Requirements
- Observable behavior and constraints.

## 6. Interfaces and data
APIs, commands, events, schemas, config, compatibility, or migration.

### Naming and identity
How every stored name or ID is created, what happens when that fails, and what happens if its source changes after data exists.

## 7. Failure behavior and lifecycle
Say what can fail, what state follows, whether the system retries, and how it recovers. Cover startup, config or state changes, work in flight, shutdown, and what happens when several things fail together.

## 8. Security, privacy, and operations
State the trust boundary, authorization checks, sensitive data handling, and operational impact. Name shared limits such as rate limits, connections, disk, memory, or cost. Say what happens at each limit.

## 9. Acceptance criteria
- `AC-1`: Testable condition that proves the work is complete.

## 10. Test approach
How each `INV-n` and `AC-n` will be proved. Cite the IDs.

## 11. Risks and tradeoffs
- Risk and mitigation.

## 12. Open questions
- Question, and whether it blocks starting work.

## 13. Out of scope
- Related work this design does not include.