# Kimball Modelling Skill — Claude Code Plugin

A professional Kimball dimensional modelling assistant for data consultants. Guides Claude through the complete modelling lifecycle for any business, with deep playbooks for **SaaS B2B** and **e-commerce / multi-brand** companies.

---

## What it does

When invoked as a Claude Code skill, this plugin produces a full set of professional data modelling artifacts:

| Artifact | Description |
|---|---|
| Business Context Brief | Extracted from website research and public sources before any interviews |
| Value Chain Diagram | End-to-end business process map with fact table candidates per stage |
| Stakeholder Interview Guide | Role-specific question sets (Executive, Analyst, Power User, Systems Owner) |
| Glossary / Definition Register | Surfaces and resolves conflicting definitions across teams |
| Bus Matrix | Master map of business processes × conformed dimensions |
| Grain Statements | One per fact table, in plain business language, for stakeholder sign-off |
| Dimension Attribute Lists | With SCD type recommendations per attribute |
| Fact Candidate Tables | With additivity flags and source system mapping |
| Reporting Validation Checklist | Validates the model against the key reports that run the business |

---

## Quick start

```
You are a senior Kimball data modelling consultant. Use the Kimball Modelling Skill.

Business: [company name]
Website: [URL]
Business type: saas-b2b | ecommerce | hybrid
Mode: full | interview-only | artifacts-only | reporting-only
Context: [additional context]
```

### Modes

| Mode | Use when |
|---|---|
| `full` | Starting a new engagement from scratch |
| `interview-only` | Preparing for stakeholder sessions |
| `artifacts-only` | Interview notes are ready, skip discovery |
| `reporting-only` | Validating an existing model |

---

## Repository structure

```
kimbo/
├── SKILL.md                          # Main skill instructions and orchestration logic
├── README.md                         # This file
│
├── agents/                           # Specialist agents — one per role
│   ├── researcher.md                 # Business intelligence from public sources
│   ├── interviewer.md                # Stakeholder interview design and synthesis
│   ├── kimball-expert.md             # Technical modelling authority and reviewer
│   ├── designer.md                   # Artifact structure and visual presentation
│   └── copywriter.md                 # Plain-language prose for all written content
│
├── templates/                        # Blank templates for all artifacts
│   ├── business-context-brief.md
│   ├── interview-guide.md
│   ├── bus-matrix.md
│   ├── grain-statements.md
│   ├── dimension-sheet.md
│   ├── fact-candidate-table.md
│   ├── glossary.md
│   └── reporting-validation.md
│
├── references/                       # Reference material
│   ├── kimball-concepts.md           # Core dimensional modelling concepts
│   ├── saas-metrics.md               # SaaS metric definitions and modelling notes
│   └── ecommerce-metrics.md          # E-commerce metric definitions and modelling notes
│
├── examples/                         # Worked examples
│   ├── smoobu/
│   │   └── smoobu-complete-model.md  # Full model for a SaaS B2B (property mgmt)
│   └── natsana/
│       └── natsana-complete-model.md # Full model for multi-brand e-commerce (supplements)
│
└── evals/
    └── evals.json                    # Evaluation test cases for skill quality testing
```

---

## Agent team

The skill uses five specialist agents working in sequence. Each has a defined role and a clear handoff chain.

| Agent | Role | What they care about |
|---|---|---|
| **Researcher** | Builds business intelligence from public sources before any interview | Completeness of the Business Context Brief; vocabulary conflicts; tech stack signals |
| **Interviewer** | Designs role-specific interview guides and synthesises session outputs | Surfacing the right questions for each role; capturing definition conflicts precisely; never letting vague answers pass |
| **Kimball Expert** | Technical modelling authority and rigorous reviewer | Grain correctness; additivity errors; conformed dimension integrity; SCD decisions; nothing leaves without passing the quality checklist |
| **Designer** | Structures artifacts for readability and visual clarity | Hierarchy before detail; tables for comparison, prose for narrative; consistent conventions throughout |
| **Copywriter** | Writes plain-language prose for all written content | Business readers and technical readers simultaneously; the business's own vocabulary; no jargon in business-facing sections |

The handoff chain: **Researcher → Interviewer → Kimball Expert → Designer → Copywriter → MODEL_REPORT**

Nothing passes from the Kimball Expert forward without passing the full quality checklist. The Copywriter receives the vocabulary register from the Researcher at the start of the engagement.

---

## Business type playbooks

### SaaS B2B
- MRR waterfall as the north star report
- Accumulating snapshot for subscription lifecycle (trial → paid → churned)
- SCD Type 2 on Account (CSM owner, tier) and Plan (pricing) for historical attribution
- Feature usage as a leading churn indicator
- Commission vs. flat-fee revenue requires explicit definition in the glossary

**Priority build order:** Date → Account → Plan → Subscription Revenue → Trial Snapshot → Feature Usage

### E-commerce / Multi-brand
- Contribution margin waterfall as the north star report
- Brand is a conformed dimension — build it first
- Amazon customers are anonymised — Customer dimension is DTC-only
- Returns must be a separate fact table (never netted against Orders)
- ACOS and all ratios are non-additive — store components, derive in BI
- Inventory is a periodic snapshot — semi-additive across time

**Priority build order:** Date → Product → Brand → Channel → Orders → Returns → Advertising → Inventory

---

## Worked examples

Two complete end-to-end examples are included, based on real companies researched from public sources:

- **Smoobu** — SaaS B2B property management software for short-term rental hosts
- **Natsana** — Multi-brand nutritional supplements, Amazon-first with DTC expansion

Each example includes a complete business context brief, bus matrix, grain statements, dimension attribute lists, fact candidate tables, glossary, and reporting validation.

---

## Evals

Four evaluation test cases are included in `evals/evals.json`:

| Eval | Tests |
|---|---|
| eval-0 | Full SaaS modelling from website URL only |
| eval-1 | Full e-commerce modelling for multi-brand company |
| eval-2 | Interview guide generation for specific role |
| eval-3 | Reporting validation against an existing model |

Run evals using the [skill-creator](../skill-creator/) skill.

---

## Key modelling rules enforced by this skill

1. Never skip the grain declaration — everything depends on it
2. Always store components, not derived ratios (ACOS, NRR, conversion rates)
3. Conformed dimensions must have a single agreed business definition — resolve conflicts in the glossary before building
4. Returns belong in a separate fact table, not netted against orders
5. Semi-additive facts (inventory, MRR balance) must be flagged — they cannot be summed across time periods
6. SCD Type 2 is required wherever "what was it then?" matters for historical reporting

---

## Contributing

This is a living skill. To improve it:
1. Add new worked examples in `examples/`
2. Add eval test cases to `evals/evals.json`
3. Extend the playbooks in `SKILL.md` for additional business types (marketplace, fintech, media, etc.)
4. Use the skill-creator skill to run evals and iterate

---

## Based on

- Ralph Kimball & Margy Ross, *The Data Warehouse Toolkit* (3rd edition)
- Kimball Group dimensional modelling techniques
- Practical consulting experience with SaaS and e-commerce data teams