<!-- The DESIGN doc captures the "why": principles, goals, trade-offs, --> <!-- decisions, rejected alternatives, unresolved questions. --> <!-- It pairs with implementation.md (the "how") in the same folder. --> <!-- This template is a preference, not a hard requirement — write in --> <!-- whatever structure best conveys the design. Omit this file entirely --> <!-- if the feature has no design rationale worth recording yet; a folder --> <!-- may ship with only implementation.md. -->

[Feature] — Design & Principles

Summary

One paragraph: what this is, why it matters, and the contract it defines for its consumers. For the machinery that realizes it, link implementation.md.

Design principles / Goals

<!-- The constraints and intentions that govern the feature. Capture the --> <!-- *why*: trade-offs considered, alternatives rejected, known pitfalls. --> <!-- Number principles if code refers back to them (e.g. "principle 2"). -->

Unresolved Questions

• Things not yet decided or worth revisiting. Skip this section if none.

Related

• implementation.md — the machinery that realizes this
• ../other-feature/implementation.md - other features that are relevant to this one