Initial commit

docs/reference/conventions.md

@@ -0,0 +1,64 @@
+# Project Conventions
+
+This page is the quick reference for conventions that a human reviewer is likely to check first.
+For the philosophy behind these conventions, read the explanation docs.
+
+## Naming
+
+- Use domain language, not generic programmer words.
+- Prefer explicit lifecycle states such as `DraftItem` or `ActiveOrder` over one object with a broad `status` field.
+- Use nouns for stateful objects, past-tense facts for events, and imperative verb phrases for commands.
+- Maintain a project-wide shared language in `shared-language.md`.
+- Maintain bounded-context shared language in `design/workflows/<bounded-context-slug>/shared-language.md`.
+- Record feature-level naming decisions in `design/feature/<feature-slug>/discovery.md` and slice-level naming decisions in the workflow artifacts.
+- See `naming-lexicon.md`, `shared-language.md`, and `../explanation/naming-for-domain-modeling.md` for guidance.
+
+## Design artifact shape
+
+A complete operational design set now usually includes:
+
+- feature discovery in `design/feature/<feature-slug>/discovery.md`
+- feature decomposition in `design/feature/<feature-slug>/design.md`
+- bounded-context shared language in `design/workflows/<bounded-context-slug>/shared-language.md`
+- slice discovery, core sketch, and F# blueprint under `design/workflows/<bounded-context-slug>/<workflow-slug>/`
+- status tracking in `design/feature/<feature-slug>/status.md`
+
+Use `design-artifact-template.md` for by-hand practice and `design-artifact-structure.md` for the repository artifact layout.
+
+## Documentation organization
+
+This repo uses a modified Diátaxis structure:
+
+- `docs/tutorials/` for learning by example and practice
+- `docs/how-to/` for specific tasks such as reviewing LLM output
+- `docs/explanation/` for philosophy and architectural reasoning
+- `docs/reference/` for templates, checklists, and stable lookup material
+
+## Code structure pointers
+
+- `src/contexts/` is the default home for business code.
+- Each context keeps its own models, policies, workflows, translators, adapters, and other seams as needed.
+- `src/workflows/` is reserved for top-level workflows that coordinate multiple contexts.
+- `src/shared/` should contain only tiny ubiquitous primitives and low-meaning technical building blocks.
+
+## Module boundaries
+
+- Cross-context imports should go through the target context's public API.
+- Do not import another context's internal implementation files.
+- When data crosses context boundaries, prefer translation at the edge over sharing one rich domain type everywhere.
+
+## Decision preference
+
+- Prefer correctness, simplicity, and elegance over backwards compatibility.
+- If compatibility would preserve a worse design, require an explicit reason before keeping it.
+- Prefer combined local logic by default during initial implementation.
+- Extract a new layer, module, or helper only when it materially improves nameability, testability, reuse, boundary clarity, or duplicated complexity.
+- Good names can expose a useful seam, but naming alone does not justify extra indirection.
+
+## Review reminder
+
+When in doubt, compare the artifact being reviewed against:
+
+- `../tutorials/worked-example-truck-loading.md`
+- `review-checklist.md`
+- `design-artifact-template.md`