| 1 | # Rationale template |
| 2 | |
| 3 | The prose that ships alongside the type sketch. One page. Sentence-case headings, no boilerplate. Replace the italic notes with actual content. |
| 4 | |
| 5 | ## Problem |
| 6 | |
| 7 | *One paragraph. What we're trying to do, and what about the existing system or constraints makes the shape non-obvious. If [Phase A |
| 8 | |
| 9 | ## Usage (caller's view) |
| 10 | |
| 11 | *Write this first, before the type sketch. Show the README or quickstart the consumer reads, plus two or three realistic call sites in their own code. What they import, what they call, what comes back. The type sketch in [Shape |
| 12 | |
| 13 | ## Shape |
| 14 | |
| 15 | *The recommended architecture. Data structures first. Then how data flows through the signatures. Name the load-bearing decisions. State which invariants are encoded in types, where validation lives, and what the system deliberately does not do. Judge interface depth explicitly. State what complexity the public surface hides, what remains exposed to callers, and why the interface is no larger than needed. Cite the principle behind each decision (e.g., `per boundary-discipline |
| 16 | |
| 17 | ## Synthesis decision |
| 18 | |
| 19 | *Filled in by [arena |
| 20 | |
| 21 | ## Tradeoffs accepted |
| 22 | |
| 23 | *One bullet per tradeoff the chosen shape makes. Form: "we accept X in exchange for Y." Name anything a future reader might mistake for an oversight, including things that look like premature optimization or premature simplification.* |
| 24 | |
| 25 | ## Alternatives considered |
| 26 | |
| 27 | *Required. Name at least one concrete alternative shape, with one line on why it lost. Judge each alternative on interface depth, not implementation simplicity alone. Name the complexity it exposes to callers and the complexity it hides. Two or three alternatives belong here when the design space had real contenders. One is fine when the constraints forced the answer, with the conclusion phrased as "this was the only viable shape because..." Avoid listing flavors of the same shape. This section covers design alternatives the chosen shape considered and rejected, not other runner candidates.* |
| 28 | |
| 29 | ## Open questions and risks |
| 30 | |
| 31 | *Things you noticed during the sketch that the human needs to weigh in on, and risks worth flagging before implementation starts. Phrase as questions, not assertions, so the human's answer is the resolution rather than a comment.* |
| 32 | |
| 33 | ## Next implementation step |
| 34 | |
| 35 | *The first thing to build against the sketch. One sentence. What you'd start writing immediately after synthesis (or after Phase D sign-off, if a checkpoint was opted into).* |