# Data Modeling

Designs the warehouse and semantic layer, source-to-mart structure, dimensional...

- Repository: https://github.com/cbrock84/headcount (2554 stars)
- Category: Design
- License: MIT
- Last updated: 2026-10-18
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add cbrock84/headcount --skill data-modeling -g -a claude-code -y`
Codex: `npx skills add cbrock84/headcount --skill data-modeling -g -a codex -y`
Cursor: `npx skills add cbrock84/headcount --skill data-modeling -g -a cursor -y`
Gemini CLI: `npx skills add cbrock84/headcount --skill data-modeling -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add cbrock84/headcount`

## Description

Designs the warehouse and semantic layer, source-to-mart structure, dimensional modeling, grain, slowly changing dimensions, and the metric layer analytics reads through. Use this to design or restructure a warehouse, model a new source, decide on grain or table structure, build a semantic or metric layer, or diagnose why queries are slow, wrong, or impossible to write.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Data modeling

## Layers, and why the middle one matters

Three layers, each with one job:

1. **Raw**, source data, append-only, otherwise unmodified. Do not apply *business* logic on
   ingest: you cannot recover what you discarded, and the logic will need to change retroactively.

   **Privacy and security transformations are the exception, and belong at ingest.** Credentials and
   secrets should never land in the warehouse at all. Personal data that is not needed should be
   dropped rather than stored and governed later, and identifiers you must keep but rarely need in
   the clear should be tokenized or encrypted on arrival. Retention and deletion apply from ingest,
   not from the marts.

   The distinction: strip what you must not hold, keep everything you are entitled to hold, and
   leave interpretation for later.
2. **Staging**, cleaned and conformed: consistent types, standardized names, deduplicated, no
   business logic yet.
3. **Marts**, business-facing models shaped for how questions are asked.

The discipline that pays is keeping business logic out of layers 1 and 2. Logic embedded in ingestion
cannot be changed retroactively, and it will need to change.

## Grain is the decision everything follows from

State the grain of every table in one sentence: *one row per what*. "One row per order line per day"
is a grain. "Order data" is not.

Most modeling errors are grain errors, and they surface as fan-out, a join multiplying rows so every
downstream sum is inflated. If a number is mysteriously too high, check the grain before checking the
logic.

## Dimensional structure

Facts for events and measurements; dimensions for the things being described. Keep facts narrow and
long, dimensions wide and short.

Conform dimensions across facts, one customer dimension, used everywhere. Separate customer tables
per domain is how the same customer gets counted differently in two reports.

The rest: https://github.com/cbrock84/headcount/blob/HEAD/plugins/data-analytics/skills/data-modeling/SKILL.md