conceptual-modelling

Conceptual Modelling

Provisional pending the first-engagement gate. This skill's consulting-facing depth will be refined after the first real engagement that builds a domain model; treat the wiring here as the floor.

Overview

The conceptual model is the single, living, representation-agnostic definition of the domain: entities, attributes, relationships, and their meaning. It is generative — code, contracts, and documentation are derived deterministically from it, never hand-maintained in parallel. The generation layer is a make generate-models-style bridge that stays outside the LLM path (the principled answer to spec-drift and failed model-driven development): the LLM authors the source, a deterministic toolchain renders the targets.

Conditional. This skill applies only to product-development (programming) projects — repos that build software with a domain to model. A documentation-only or non-product repo does not need a conceptual model and should not scaffold one.

This skill owns the model; it does not own system topology, code layering, or normative requirements — see Boundary & Related Skills.

Where the model lives (two modes)

The model is a first-class asset with a home of its own. Pick the mode explicitly:

• In-project model/ directory (default). This is what project-setup scaffolds by default (EPIC-09): the model lives beside the code it generates, versioned with the repo. Generated artefacts land under the relevant package (e.g. models/, see cosmic-python) via make generate-models. Use this for a model owned by one product.
• Own repo / imported library. For a model shared across repos, give it its own repository and import it as a dependency (LinkML schema published as a package, or generated artefacts released as a versioned library). Each consuming repo regenerates from the pinned version.

Golden-thread implication. Model entities carry stable IDs (see ontology practices). When the model lives in its own repo, downstream code and specs cite those entity IDs across repos — the cross-repo rung of the golden thread (see ../../spine/golden-thread.md, which notes cross-repo IDs are convention-only for now).

The source: LinkML by default, not by default-only

LinkML is the wired default source for the model. It is declarative, generates many targets, and is the canonical domain-definition format the architecture skill already references for contracts.

Choosing the source is an explicit decision point — never silently defaulted:

• LinkML (default) — author the schema directly; drives all generators below.
• model2owl — a UML-driven ontology-engineering path with strong OWL, SHACL, and HTML generators. In some projects model2owl is used to generate LinkML artefacts, which then drive the other generators — so model2owl can be a prerequisite step before the LinkML generators, not an alternative to them. Surface this ordering when a project models in UML.
• Other ontology-engineering tooling exists (Protégé/OWL-first, SHACL-first, etc.); document the chosen one as a named pattern.

We deliberately do not build a source-adapter abstraction (YAGNI) — alternatives are documented as named patterns, not wired behind an interface. The source decision and the concept-level ontology policy are owned here (see references/ontology-practices.md); the LinkML craft that executes on the chosen source is owned by linkml-engineering.

Deterministic multi-target generation (the concept)

From the chosen source, code, contracts, and documentation are generated deterministically and outside the LLM path — reproducible, diffable, CI-checkable. This skill owns that this is how the model becomes artefacts; it does not own the LinkML authoring, the generator wiring, the custom templates, or the quality gates — those belong to ../linkml-engineering/SKILL.md. The semantic core (Pydantic, JSON Schema, OWL, SHACL) and the enable-on-demand targets are catalogued there; see references/generators.md for the pointer.

The seam to cosmic-python. The model owns the contract; the generated Pydantic/JSON Schema is the contract. A service's entrypoints/api consumes the generated contract — it does not redefine the domain. This skill owns the source side of that seam; linkml-engineering owns the generation that crosses it.

The craft around the model

A model is more than a schema. Two adjacent practices are part of the discipline:

• Diagrams alongside the formal model. Generate/maintain Mermaid (and other) diagrams from or beside the model so the human view and the formal view stay in step. Architecture's C4/UML class diagrams are a consumer of the same domain concepts — keep them coherent, but the formal source of truth is the model.
• Terminology, disambiguation, and definitions management. The glossary / ubiquitous-language layer: every model class is a term with a definition, and OpenSpec specs reference those classes as ubiquitous language. See references/terminology-management.md.

Boundary & Related Skills

This skill OWNS: the living conceptual model (representation-agnostic source of domain truth); conceptual data modelling in UML; the concept-level ontology policy (stable-IRI policy, modularity, vocabulary-reuse principle); the model-source decision (LinkML-direct vs model2owl-first); and terminology / definitions / glossary management (ubiquitous language).

This skill REUSES:

• Representation-agnostic modelling craft (reusable-property and URI-everywhere principles, naming, anti-patterns, guardrails) → ../modelling-conventions/SKILL.md. This skill applies those conventions; it does not restate them.

This skill DELEGATES:

• The LinkML craft — authoring, generation, custom templates, quality gates, per-module output → ../linkml-engineering/SKILL.md. This skill picks the source and owns the model; linkml-engineering executes the LinkML.
• System/solution architecture — C4 levels, ADRs, the contract-first order of artifacts → ../architecture/SKILL.md. Architecture authors which contracts exist; this skill owns the domain model that backs them.
• Code layering and what consumes the generated contract → ../cosmic-python/SKILL.md. entrypoints/api consumes the generated contract; this skill owns the model that produces it.
• Normative requirements and the spec spine → the spine specs (see ../../spine/README.md). Model classes are ubiquitous language that specs reference; specs state the rules.

Conditional: product-development (programming) projects only — see the Overview.

Related: modelling-conventions, linkml-engineering, architecture, cosmic-python.