conceptual-modeling
Conceptual Modeling
Coverage
Methodology for abstracting a real-world domain into a structured representation before any database table, API endpoint, or aggregate boundary is named. Identifies entities (distinguishable things the business tracks), attributes (properties that describe an entity), and relationships (meaningful connections between entities). Specifies cardinality (1:1, 1:N, M:N, 0..1, 1..*); distinguishes association from aggregation from composition; uses generalization / specialization with disjoint / overlapping and total / partial constraints; recognizes when an associative relationship needs to be reified into its own entity (e.g. an enrollment between Student and Course that carries grade and date). Walks the conceptual → logical → physical abstraction ladder. Validates models against business stakeholders' mental models via walk-through, scenario testing, negative testing, and terminology audit. Names the seven anti-patterns: implementation leakage, missing entity, god entity, phantom relationship, premature normalization, attribute-as-entity, unnamed relationship.
Philosophy
Every software system is a model of some real-world domain. The quality of that model determines whether the system helps or hinders its users. Without explicit conceptual modeling, the team jumps directly from requirements to code — encoding implicit assumptions that surface later as architectural debt. A requirement like "users can place orders" hides dozens of decisions: is a cart an order? can an order have multiple shipments? is a refund a new entity or a state of a payment? Conceptual modeling forces those decisions to the surface before code exists, so rework happens on a whiteboard rather than across a migration.
The discipline is anti-rigid in a specific way. Conceptual modeling stays one layer above logical modeling (tables, foreign keys, normalization) and one layer above DDD tactical design (aggregates, bounded contexts, anti-corruption layers). The moment the model speaks of UUIDs, indexes, or cascade behavior, it has fallen into logical modeling. The moment it prescribes aggregates or anti-corruption layers, it has crossed into DDD. Conceptual modeling's job is earlier and narrower: capture the domain structure clearly enough that those later design layers can proceed without guessing about the business.
1. The Three-Level Architecture
| Level | Purpose | Audience | Notation |
|---|---|---|---|
| Conceptual | What exists in the business domain | Business stakeholders, product managers | Simplified UML class diagrams, entity lists, relationship maps |
| Logical | How the data is structured, platform-independent | Architects, senior developers | Normalized schemas, interface contracts, type hierarchies |
| Physical | How the data is stored and accessed | Database engineers, backend developers | SQL DDL, index strategies, partition schemes |
More from jacob-balslev/skills
layout-composition
Use when deciding responsive page or screen structure: section order, scan pattern, grid/flex composition, breakpoints, viewport hierarchy, responsive media, and density. Do NOT use for user-goal decomposition (use `task-analysis`), navigation taxonomy (use `information-architecture`), visual polish (use `visual-design-foundations`), or component/token contracts (use `design-system-architecture`).
8context-graph
Use when designing or auditing the multi-graph context architecture of an AI-coding workspace: skill graph, document routing graph, memory index, script registry, and the cross-graph edges between them. Covers edge typing, orphan detection, connectivity health, deterministic graph synthesis signals, change-propagation checks, and drift or hub-and-spoke anti-patterns. Do NOT use for authoring one SKILL.md (use `skill-scaffold`), validating one skill (use `graph-audit`), live routing decisions (use `skill-router`), context-window budgeting (use `context-window`), or session load/drop choices (use `context-management`).
8visual-design-foundations
Use when designing or auditing visual craft: color palette, typography, spacing, elevation, rhythm, density, visual hierarchy, brand fit, contrast intent, and motion feel. Do NOT use for sign-system meaning (use `semiotics`), token/component architecture (use `design-system-architecture`), responsive structure (use `layout-composition`), or accessibility compliance (use `a11y`).
7project-knowledge-extraction
Use when extracting durable project knowledge from code, docs, issues, incidents, reports, screenshots, or conversations into reusable context such as skills, ADRs, glossaries, context docs, or memory. Do NOT use for writing a new skill contract (use `skill-scaffold`), maintaining library tooling (use `skill-infrastructure`), or generic documentation polish (use `documentation`).
6problem-framing
Use when a team is converging on solutions before agreeing on the problem, when a brief reads as a feature request, when symptoms and root needs are tangled, or when assumptions need surfacing before design work proceeds. Do NOT use for code-level bug triage, runtime failure diagnosis, or root-cause analysis of system errors — those are engineering investigation tasks, not design problem framing.
6ai-native-development
Use when reasoning about agent autonomy levels, designing auto-improve loops, evaluating AI-generated code quality, or measuring agent productivity in an LLM-assisted codebase. Covers Karpathy's three eras of software (1.0 explicit / 2.0 learned / 3.0 natural-language), the vibe-coding-vs-agentic-engineering distinction, the 0–5 autonomy slider with task-type recommendations, the one-asset / one-metric / one-time-box AutoResearch loop, Software 3.0 productivity metrics, and the documented quality regressions of ungated AI-generated code (the 'vibe hangover'). Do NOT use for choosing a specific autonomy-loop topology (use `agent-engineering`), for the per-prompt authoring discipline (use `prompt-craft`), or for reviewing the AI-generated code that comes out of a Software 3.0 workflow (use `code-review`).
6