SuperAPI AI Directory

domain-modeling

General & other

View repository

Updated 10-16 09:45

About this skill

Domain modeling

Actively build and sharpen the project's domain model during design. This is the active discipline: challenge terminology, invent edge-case scenarios, and write into the glossary and decisions at the moment concepts take shape.

File structure

Most repos have only one context:

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

If the root has GLOSSARY-MAP.md, the repo has multiple contexts. The map points to the location of each context:

/
|- GLOSSARY-MAP.md
|- docs/
|  `- adr/                          -> system-wide decisions
`- src/
   |- ordering/
   |  |- GLOSSARY.md
   |  `- docs/adr/                  -> context-specific decisions
   `- billing/
      |- GLOSSARY.md
      `- docs/adr/

Create files lazily on demand: only create them when there is content to write. If there is no GLOSSARY.md, create it when the first term is resolved. If there is no docs/adr/, create it when the first ADR needs to appear.

During a session

Challenge against the glossary

When the terminology the user uses conflicts with existing language in GLOSSARY.md , point it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y - which is it?"

Sharpen vague wording

When the user uses vague or overloaded terminology, 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 discussing domain relationships, use concrete scenarios to stress-test. Invent scenarios that probe edge cases and force the user to precisely define the boundaries between concepts.

Cross-check against the code

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

Update GLOSSARY.md in place

When a term is resolved, update GLOSSARY.mdimmediately. Don't batch it up until the end; capture it as concepts emerge. Use the format in GLOSSARY-FORMAT.md .

GLOSSARY.md must contain no implementation details at all. Don't treat GLOSSARY.md as a spec, scratch pad, or repository for implementation decisions. It is just a glossary.

Propose ADRs cautiously

Only propose creating an ADR when all three of the following hold:

  1. Hard to reverse - The cost of changing your mind later is meaningful
  2. Surprising without context - A future reader would wonder "why did they do it this way?"
  3. The result of a real trade-off - Alternatives genuinely exist, and you chose one of them for concrete reasons

If any one is missing, skip the ADR. Use the format in ADR-FORMAT.md .