Domain Design
One Process keeps the project's language and Decisions precise while Shaping or Execution changes them.
1. Use the right home
Project language lives in the repo-root Domain.md. Decisions live in docs/architecture/decisions/. Create either only when there is something to write.
2. Challenge language against Domain.md
IF a term conflicts with Domain.md:
Ask which meaning survives before writing
Call out both meanings and ask the Architect which one survives.
IF a term is vague or overloaded:
Propose the precise project word
Check Domain.md and the code, then propose the precise word that fits the project.
3. Test terms with concrete cases
Use concrete cases that probe edge cases and force precision about the boundaries between concepts.
4. Check code claims against code
When the Architect states how something works, read the code and surface any contradiction.
5. Update Domain.md when a term resolves
Write the term immediately at the repo root.
Template: Term: {One or two sentences defining what it IS, not what it does.} Avoid: {the words it replaces}
One word wins
Put replaced words under _Avoid_. Project-specific terms go in Domain.md; general programming concepts stay out even when the project uses them heavily. Group terms under subheadings when natural clusters emerge.
Keep implementation details out
Domain.md holds the project's language, not implementation decisions.
6. Propose Decisions, then record the Architect's choice
Propose a Decision only when all three hold: it is hard to reverse, it is not self-evident from the code, and it is the result of a real trade-off. The Architect makes the Decision, typically through /interview.
Template: docs/architecture/decisions/000N-<the-decision>.md
# {The Decision}
{One to three sentences: situation, choice, and WHY — plus measured scores when an experiment produced them.}