# Domain Modeling

> Use when building or sharpening a project's domain model and recording ADRs

- Skill: `loopyluci/domain-modeling` (Agent Skill)
- Install (CLI): `npx skillmds@latest add loopyluci/domain-modeling`
- Raw SKILL.md: https://api.skillmd.com/api/skills/loopyluci/domain-modeling/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: LoopyLuci (https://skillmd.com/u/loopyluci)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/loopyluci/domain-modeling

---


# Domain Modeling

Actively build and sharpen the project's domain model as you design. Challenge terms, invent edge-case scenarios, and write the glossary and decisions down the moment they crystallize.

## File structure
Most repos have a single context:

```
/
|- CONTEXT.md
|- docs/
|   |- adr/
|       |- 0001-event-sourced-orders.md
|       |- 0002-postgres-for-write-model.md
|- src/
```

Create files lazily - only when you have something to write.

## During the session
- Challenge against the glossary when the user uses a term that conflicts
- Capture edge cases: scenarios that stress the model
- Propose ADRs: record architectural decisions with context, decision, and consequences
- Tie concepts to code locations

## Common Pitfalls

- **Creating files before you have something to write**: Create CONTEXT.md and ADR files lazily - only when you have resolved terms or decisions to record. Empty files are noise.
- **Terms that conflict with existing glossary without flagging**: When the user uses a term that conflicts with what is in the glossary, stop and discuss the discrepancy.
- **Neglecting the single/multi-context distinction**: Most repos have one context, but some need CONTEXT-MAP.md. Applying single-context rules to a multi-context repo creates confusion.

## Code Examples

```markdown
# Example ADR
## ADR-0001: Event-Sourced Order Lifecycle

**Context:** Orders need full audit trail and the ability to replay
state after failures.

**Decision:** Model Order as an event stream:
- OrderCreated, ItemAdded, ItemRemoved, OrderSubmitted, OrderPaid
- Current state is folded from the stream
- No mutable state table

**Consequences:**
- (+) Full audit trail by design
- (+) Temporal queries are free
- (-) More complex read-model projection needed
```

## Verification Checklist

- [ ] CONTEXT.md created/updated with resolved terms
- [ ] ADRs recorded for architectural decisions
- [ ] Terminology conflicts resolved with user
- [ ] Single or multi-context structure determined
- [ ] Files created only when content exists to write