Polaris: Skill for Codex

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.