# 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`