aTeering/skills

Domain Modelling

Keep one shared, lean source of truth for what things mean in this project, so code, docs, tickets, and conversations use the same words for the same things.

Focus: $ARGUMENTS (if empty, model whatever is under discussion in this session).

Zero silent assumptions. The user owns what terms mean. A definition, canonical name, synonym, relationship, cardinality, or invariant you inferred from code, docs, or conversation is an assumption until the user confirms it. Track them as ✅ confirmed · ❓ unconfirmed · ❌ rejected, and only write confirmed ones into the domain doc as fact.

Where the model lives

• If GLOSSARY.md or docs/domain.md already exists, use it (prefer the existing file; never create both).
• Otherwise create docs/domain.md using the structure below.

Process

1. Read the current domain doc and the code that implements the concepts in focus (types, schemas, DB models, API contracts). Code is evidence of the actual model; the doc is the intended one — note any drift. Neither tells you what the user means; ask about any drift instead of picking a side.
2. Extract candidate terms from the conversation, spec, or ticket. For each, propose whether it is a new term, an existing term, or a synonym of an existing term, and get the user to confirm. Two words that look alike may be different concepts.
3. Resolve ambiguity with the user. Ask short, concrete questions:
   • "Is a Workspace the same thing as an Organisation, or can one org have many workspaces?"
   • "Can an Order exist without a Customer? What must always be true about an Order?" Agree on one canonical name per concept with the user (you may recommend one); list rejected synonyms as Avoid.
4. Define boundaries: identity (entity vs value object), ownership/aggregate roots, cardinality, lifecycle/states, and invariants. Note which bounded context a term belongs to if the project has more than one. Propose these from the code if helpful, but confirm each one with the user.
5. Update the doc with confirmed items only — minimal diff, alphabetical within sections, no essays. If a definition changes meaning, say so in the commit/PR, and flag code that now uses the term incorrectly. If the user wants to stop with items unresolved, add them under ## Open Questions marked ❓, never into the glossary.
6. Report what you added/changed and any code ↔ model drift you found (with file:line), and any ❓ items still open.

Doc structure (keep it lean)

# Domain Model

## Glossary
| Term | Definition | Avoid |
|------|------------|-------|
| Order | A customer's confirmed request to buy one or more Products. | purchase, cart |

## Entities & Aggregates
### Order (aggregate root)
- Identity: `OrderId`
- Contains: OrderLine (1..n)
- States: draft → placed → paid → shipped | cancelled
- Invariants: total ≥ 0; cannot ship unless paid

## Relationships
- Customer 1 — n Order

## Bounded Contexts (optional)
- Billing: Invoice, Payment

Rules: one sentence per definition where possible; define terms using other glossary terms; no implementation details unless they are the domain (e.g. an ID format customers see).