Initial commit

docs/reference/design-artifact-template.md

@@ -0,0 +1,111 @@
+# Design Artifact Template
+
+Use this template when drafting a design manually or when asking an LLM to produce a design artifact for review.
+
+## 1. Story
+
+Write the business situation in plain language.
+
+```text
+A <role> attempts to <action>.
+If <condition>, it succeeds.
+If <condition>, it fails.
+```
+
+## 2. Event storming
+
+### Command
+
+```text
+<ImperativeVerbNoun>
+```
+
+### Timeline
+
+1. <user intent>
+2. <business evaluation>
+3. <success or failure fact>
+
+### Events
+
+```text
+<SuccessEvent>
+<FailureEvent>
+```
+
+## 3. Core sketch
+
+Write the first policy sketch with rough concepts if needed.
+
+```fsharp
+decide : NeededInput -> NeededState -> Result<SuccessEvent, FailureEvent>
+```
+
+Then rewrite it using domain-specific concepts.
+
+## 4. Domain model
+
+### Primitives
+
+```fsharp
+type ExampleId = string
+```
+
+### Compound objects
+
+```fsharp
+type Example = {
+  Id: ExampleId
+}
+```
+
+### State variants
+
+```fsharp
+type ActiveExample = { Id: ExampleId }
+type ArchivedExample = { Id: ExampleId }
+
+type ExampleState =
+  | Active of ActiveExample
+  | Archived of ArchivedExample
+```
+
+### Events
+
+```fsharp
+type ExampleSucceeded = { Id: ExampleId }
+type ExampleRejected = { Reason: RejectionReason }
+```
+
+## 5. Final contract
+
+```fsharp
+decide : Input -> State -> Result<SuccessEvent, FailureEvent>
+apply : State -> SuccessEvent -> State
+workflow : InputId -> Effect<Response>
+```
+
+## 6. Shared language and naming decisions
+
+Record the canonical words for this feature so design and code stay consistent. If a term is project-wide rather than feature-local, also add it to `docs/reference/shared-language.md`.
+
+### Canonical terms
+
+- `<Preferred term>`: short definition
+- `<Preferred term>`: short definition
+
+### Rejected synonyms
+
+- Use `<Preferred term>`, not `<Rejected term>`
+- Use `<Preferred term>`, not `<Rejected term>`
+
+### Naming grammar for this feature
+
+- Commands use: `<ImperativeVerbNoun>`
+- Events use: `<PastTenseFact>`
+- States / objects use: `<DomainNoun>`
+- Workflow names use: `<verbNoun>`
+
+## 7. Reviewer notes
+
+Document any assumptions, open domain questions, or naming choices the reviewer should inspect.