domain-modeling

Files (5)

• ADR-FORMAT.md
• CONTEXT-FORMAT.md
• LICENSE
• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Domain Modeling

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's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)

## File structure

Follow the repository's existing locations and document responsibilities. When it has no established convention, a single-context layout can be:

```
/
├── 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.

## Start from the problem

Before adding a term, entity, or lifecycle, state the operational problem it solves. Require it to own at least one distinct invariant, decision, or workflow that the existing model cannot express. If its only justification is a possible future need, leave it out and record that need as an open question instead.

Re-run this test whenever the model grows much faster than the problem statement. Subtract concepts before refining their mechanics.

## 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're 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.

For an operation that creates the first authorization boundary, name the
authority that exists before the boundary does. Never require a permission
inside the boundary being created. Authorize against an existing identity or
platform scope; treat obsolete grants only as compatibility data.

For immutable history, identify any mutable staging state as well. Ask when it opens and closes, whether it can be cited, what exact state a citation names, and how replay or retry behaves. Never call a record immutable while an unnamed buffer can still change what its identifier denotes.

For recovery, distinguish the system's actual state, the evidence currently observed, and the transitions that evidence permits. Missing shutdown evidence is not confirmed termination; uncertain exclusive ownership remains unsafe until fencing or reconciliation proves otherwise.

For deferred work, separate facts pinned at acceptance from mutable authorization, configuration, and resource ownership. Name which facts must be revalidated when the work becomes eligible or starts; an earlier authorization decision is not ongoing permission.

### 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. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).

For a new glossary, keep domain definitions separate from implementation plans and scratch notes. If an existing `CONTEXT.md` has broader documented responsibilities, preserve them and update only the relevant domain material.

### 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).

### Reconcile the whole contract

After changing or deferring a term, use `rg` to find it and related names across `CONTEXT.md` and design documents. Reconcile glossary definitions, invariants, operations, type sketches, examples, scenarios, tool lists, open questions, and delivery scope. A deferred concept must disappear from initial contracts and tools, not only from prose.

From maxatwork/skills, MIT.

More from maxatwork/skills