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.

Status: Proposed for review

• Observable behavior and constraints.

• AC-1

  : Testable condition that proves the work is complete.

• Risk and mitigation.

• Question, and whether it blocks starting work.

• Related work this design does not include.

undefined

• Start with the simplest useful explanation. Write for a new teammate, not someone who already knows the project.
• Prose is the default. Use bullets only for real lists, such as config fields, acceptance criteria, risks, and out of scope.
• A bullet cannot carry a decision by itself. Write the reason next to it in a sentence.
• Use plain words. Say "the process crashed" instead of "an availability event occurred". Prefer short sentences.
• Define a term the first time you use it, or do not use it.
• Keep current architecture and proposed behavior distinct. Link to

  ARCHITECTURE.md

  when it exists and say exactly which current boundary changes.
• Give each changed component a positive and negative boundary: what it owns and what it does not own.
• Use numbered top-level sections so reviewers can refer to stable parts of the design.
• Once another artifact cites an

  INV-n

  or

  AC-n

  , keep that ID attached to the same rule. Do not renumber or reuse existing IDs. Give additions the next unused ID.
• Use diagrams only when they make system context, dependency direction, data flow, or lifecycle materially clearer.
• Prefer one clear recommendation over a list of options.
• Record rejected options only when the tradeoff matters later.
• Do not repeat the same fact in several sections with different wording.
• Do not use em dashes.

1. Executive summary. Can a new teammate understand the problem, outcome, approach, and main downside without reading the rest of the document?
2. Architecture fit. Does the design show the current system boundary, the boundary being changed, and the owner of each new responsibility?
3. Names and identity. Where does every stored identifier come from? What happens when it is missing, unclear, or changes after data exists?
4. Failure and recovery. What creates a bad state? Does the system retry, how long does it wait between attempts, and can it recover without a restart? What happens when everything is bad at startup?
5. Security and privacy. Where is identity established, authorization enforced, untrusted input validated, and sensitive data exposed or retained?
6. Shared resources. What limited resource does the feature use? State the budget and what happens at the limit.
7. Timing and fairness. Replace words such as "eventually" and "will not starve" with a bound someone can test.
8. Lifecycle. Cover config reload, enable and disable behavior, work already in flight, and shutdown.
9. Undefined terms. Define words that carry a specific meaning in the design.
10. Either/or acceptance criteria. Do not allow both sides of "recovers or retains" to pass. Choose one observable behavior.