domain-modeling

Files (3)

• ADR-FORMAT.md
• GLOSSARY-FORMAT.md
• SKILL.md

SKILL.md (first lines)

# Domain Modeling

Build the project's **ubiquitous language** while you design: one precise word
per concept, used the same way in conversation, docs, and code. This skill is
the active discipline of changing that language. Reading `GLOSSARY.md` for
vocabulary is a habit any skill can have; this is for when the model itself
is moving.

## Where the files live

Follow the repo's existing convention when it has one. Otherwise:

- **One context (most repos):** `GLOSSARY.md` at the root, ADRs in `docs/adr/`.
- **Several contexts:** a root `GLOSSARY-MAP.md` lists each context, where its
  `GLOSSARY.md` lives, and how the contexts relate. System-wide ADRs stay in
  `docs/adr/`; context-specific ones sit beside that context's glossary.

Create files lazily: the glossary when the first term is resolved, the ADR
directory when the first ADR is written.

## During the conversation

- **Challenge against the glossary.** When the user uses a term in a way that
  conflicts with its glossary definition, say so at once: "The glossary
  defines cancellation as X; you seem to mean Y. Which is it?"
- **Sharpen fuzzy words.** When one word is doing several jobs ("account" for
  both Customer and User), propose a canonical term for each concept.
- **Stress-test with scenarios.** Invent concrete edge cases that force a
  precise boundary between two concepts.
- **Check the code.** When the user says how something works, look at whether
  the code agrees, and surface any contradiction.

## Recording

- **Glossary:** update it the moment a term is resolved, not in a batch at the
  end, following [GLOSSARY-FORMAT.md](GLOSSARY-FORMAT.md). The glossary holds
  terms, how they relate, and resolved ambiguities; implementation details,
  plans, and specs go elsewhere.
- **ADRs:** offer one only when a decision is hard to reverse, would surprise
  a future reader, and came from a real trade-off. All three, or skip it.
  Format and examples are in [ADR-FORMAT.md](ADR-FORMAT.md).

Done when every term resolved in the session is in the glossary with its
avoided synonyms, and every decision that met the ADR bar was offered as one.

From dougborg/harness-kit, Apache-2.0.

More from dougborg/harness-kit