Domain Modeling

Actively build and sharpen the project's domain model as you design.

This is the active discipline: challenge terms, invent edge-case scenarios, reconcile stated behavior with the code, and capture resolved vocabulary as it crystallizes.

Merely reading CONTEXT.md for vocabulary is not $domain-modeling.

File Structure

Most repositories use a single domain glossary:

/
├── CONTEXT.md
├── docs/
│   └── adr/
└── src/

If CONTEXT-MAP.md exists, use it to locate the appropriate bounded-context glossary.

Do not assume a bounded context, package, or wiki entity automatically maps one-to-one to another.

Create glossary files lazily — only when there is resolved vocabulary to record.

During the Session

Challenge Against the Glossary

When the user uses a term inconsistently with CONTEXT.md, surface the conflict immediately.

Example:

CONTEXT.md defines "cancellation" as X, but this discussion seems to use it as Y. Are those intended to be different concepts?

Do not silently redefine an existing canonical term.

Sharpen Fuzzy Language

When a term is vague or overloaded, propose a more precise distinction.

Example:

You're using "account" for both the customer organization and the authenticated user. Are those actually the same domain concept?

Prefer canonical domain language over generic software terminology.

Canonical-Term Qualification Standard

Use the shortest natural canonical noun or noun phrase that remains semantically unambiguous among the project's first-class domain concepts.

Add a qualifier only when it earns its place by resolving a real domain ambiguity, establishing a necessary semantic boundary, or preventing misleading overloading. Do not add qualifiers merely because the underlying word is generic English.

Qualification should resolve ambiguity, not compensate for an imprecise definition.

Apply this canonical-term qualification test before freezing a canonical term:

1. First-class collision: Does the bare noun plausibly collide with another first-class domain concept in this product? If yes, qualify it.
2. Information gain: Does the qualifier add meaningful semantic information, or merely repeat what the canonical definition already establishes? Prefer the bare noun when the qualifier is redundant.
3. Narrowing risk: Would the qualifier incorrectly imply narrower ownership, scope, cardinality, origin, or lifecycle than the concept actually has? Reject a qualifier that makes the term less accurate.
4. Context independence: Is the bare noun still clear when extracted from its ideal paragraph and used in glossary entries, schemas, APIs, events, UI labels, logs, or cross-domain discussion? Qualify it when the bare term becomes materially ambiguous outside local prose.
5. Canonical capitalization: Can canonical capitalization and the glossary definition distinguish the domain concept adequately from ordinary lowercase English usage? Do not lengthen canonical vocabulary solely to eliminate harmless natural-language collisions.

Examples:

• Decision Evaluation is preferable to bare Evaluation because evaluation is materially overloaded across model, evidence, policy, workflow, and other product concerns.
• Outcome is preferable to Decision Outcome because its canonical definition is already decision-relative and the qualifier adds little while suggesting an unnecessarily terminal result.
• Lesson is preferable to Decision Lesson because one Lesson may synthesize learning across multiple Investment Decisions; the qualifier would misleadingly narrow the concept.

When two candidate names remain equally precise after this test, prefer the shorter and more natural term.

Discuss Concrete Scenarios

Stress-test domain relationships with specific scenarios, especially around:

• identity;
• lifecycle;
• state transitions;
• ownership;
• cardinality;
• partial operations;
• invalid states;
• temporal behavior.

Use scenarios to expose ambiguity, not to invent product behavior arbitrarily.

Cross-Reference With Code

When a claim describes behavior that should already exist, inspect the implementation.

If code and the proposed domain model disagree, surface the discrepancy rather than silently deciding which is correct.

The discrepancy may indicate:

• incorrect vocabulary;
• incomplete implementation;
• an overloaded concept;
• a missing architectural decision.

Resolve the semantic question first.

Update CONTEXT.md Inline

When a term or distinction is resolved, update CONTEXT.md immediately rather than batching glossary changes until the end.

Follow CONTEXT-FORMAT.md when present.

CONTEXT.md is a domain glossary only.

It may contain:

• canonical terms;
• precise definitions;
• meaningful distinctions;
• domain-level relationships;
• useful aliases or deprecated terminology.

It must not contain:

• implementation details;
• class or module paths;
• database choices;
• architecture decisions;
• project status;
• roadmap items;
• Planned work.

A glossary entry explains what a domain concept means, not how Polaris implements it.

Keep Domain and Architecture Separate

A resolved domain statement belongs in CONTEXT.md.

An architectural decision belongs through $to-adr-doc when its criteria are met.

Durable current or proposed architecture that does not warrant an ADR belongs through $to-doc.

If an existing non-ADR document needs reclassification, use $classify-doc.

Do not use CONTEXT.md as a substitute for architecture documentation.

Living Entity Wiki

A CONTEXT.md vocabulary change is not by itself a $wiki-sync trigger.

Do not copy glossary definitions into entity pages or create wiki/log.md entries merely because terminology changed.

Use $wiki-sync only when the domain-modeling session also causes one of its normal triggers, such as:

• substantive source-code changes;
• substantive docs/current/ or docs/proposed/ changes;
• ADR lifecycle activity;
• an approved entity-topology change.

Do not derive wiki entities mechanically from:

• domain terms;
• aggregates;
• bounded contexts;
• domain services.

Entity topology remains governed by wiki/_schema.md and $wiki-sync.

Source Conflicts

If domain modeling exposes material disagreement between accepted ADRs, current architecture docs, and verified implementation evidence, surface [source-conflict].

Do not resolve an architectural conflict by redefining terminology in CONTEXT.md.

Handoff

Report:

• canonical terms added or changed;
• important distinctions resolved;
• unresolved domain questions;
• implementation/domain discrepancies discovered;
• any $to-adr-doc, $to-doc, $classify-doc, or $wiki-sync outcome.

Do not report a wiki change when only CONTEXT.md changed.