---
name: domain-modeling
description: Model-invoked. Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a CONTEXT.md, or recording or editing an ADR.
---

# /domain-modeling - Domain modeling reference

Every message to the operator follows the `operator-communication`
skill: load it before your first message.

If a `tw_*` tool or the workflow misbehaves, refuses you, or otherwise surprises you, invoke the `workflow-failure` skill before improvising.

Actively build and sharpen the project's domain model as you design. This is
the *active* discipline: challenging terms, inventing edge-case scenarios, and
writing the glossary and decisions down the moment they crystallise. (Merely
*reading* `CONTEXT.md` for vocabulary is not this skill: that is a one-line
habit any skill can do. This skill is for when you are changing the model, not
just consuming it.)

## File structure

Most repos have a single context:

```
/
├── CONTEXT.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/
```

If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The
map points to where each one lives:

```
/
├── CONTEXT-MAP.md
├── docs/
│   └── adr/                          ← system-wide decisions
├── src/
│   ├── ordering/
│   │   ├── CONTEXT.md
│   │   └── docs/adr/                 ← context-specific decisions
│   └── billing/
│       ├── CONTEXT.md
│       └── docs/adr/
```

Create files lazily: only when you have something to write. If no `CONTEXT.md`
exists, create one when the first term is resolved. If no `docs/adr/` exists,
create it when the first ADR is needed.

The skill infers which structure applies: if `CONTEXT-MAP.md` exists, read it
to find contexts; if only a root `CONTEXT.md` exists, single context; if neither
exists, create a root `CONTEXT.md` lazily when the first term is resolved.

## During the session

### Challenge against the glossary

When the user uses a term that conflicts with the existing language in
`CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as
X, but you seem to mean Y. Which is it?"

### Sharpen fuzzy language

When the user uses vague or overloaded terms, propose a precise canonical term.
"You are saying 'account': do you mean the Customer or the User? Those are
different things."

### Discuss concrete scenarios

When domain relationships are being discussed, stress-test them with specific
scenarios. Invent scenarios that probe edge cases and force the user to be
precise about the boundaries between concepts.

### Cross-reference with code

When the user states how something works, check whether the code agrees. If you
find a contradiction, surface it: "Your code cancels entire Orders, but you just
said partial cancellation is possible. Which is right?"

### Update CONTEXT.md inline

When a term is resolved, update `CONTEXT.md` right there. Do not batch these up:
capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).

`CONTEXT.md` should be totally devoid of implementation details. Do not treat
`CONTEXT.md` as a spec, a scratch pad, or a repository for implementation
decisions. It is a glossary and nothing else.

### Offer ADRs sparingly

Only offer to create an ADR when all three are true:

1. **Hard to reverse**: the cost of changing your mind later is meaningful
2. **Surprising without context**: a future reader will wonder "why did they do
   it this way?"
3. **The result of a real trade-off**: there were genuine alternatives and you
   picked one for specific reasons

If any of the three is missing, skip the ADR. Use the format in
[ADR-FORMAT.md](./ADR-FORMAT.md).

## Expected modeling output

Return a concise **domain model** containing:

- **Boundary and actors:** scope, exclusions, and relevant outcomes.
- **Concept catalog:** concept kind (entity, value, event, or policy),
  identity, purpose, owner, and key attributes.
- **Relationship map:** direction, cardinality, ownership/reference semantics,
  and mutation authority.
- **Invariant catalog:** numbered, testable rules with classification, owner,
  trigger, and failure outcome.
- **Lifecycle/state table:** state, allowed transition, trigger, guard, actor,
  side effect, and terminal-state notes.
- **Terminology:** canonical terms, aliases, definitions, units, and unresolved
  naming conflicts.
- **Uncertainty and decisions:** open questions, assumptions, evidence, settled
  decisions, and consequences.

Validate the model with concrete examples and counterexamples. Present
unresolved uncertainty rather than inventing domain rules.