---
name: ba-concept-model
description: >
  Use this skill whenever a business analyst, architect, or project team needs to identify,
  define, and structure the core business objects (concepts) of a domain — even if they don't
  use that exact term. Trigger on phrases like: "what are the key things the business manages",
  "define our business objects", "build a concept model", "what data entities do we need",
  "domain model", "business glossary", "core concepts", "object model", or when someone wants
  to understand what a business manages before designing systems, processes, or value streams.
  Also trigger when a Capability Map has been produced and the user wants to validate coverage
  through the objects that ground the capabilities, or when preparing for a VCC session.
  The skill handles any input — transcripts, charters, existing capability maps, or verbal
  descriptions. Always load ba-taxonomy-standard alongside this skill.
---

# BA Concept Model Skill

## Purpose

Produce a rigorous Business Concept Model — a structured taxonomy of the core business objects
a domain manages — from any input. The Concept Model is the semantic backbone of the business
architecture: it names and defines the things the organisation cares about, classifies their
relationships, and cross-validates the Capability Map by ensuring every capability is grounded
in a named object and every object has at least one corresponding capability.

A Concept Model is not a data model. It does not define tables, attributes, or database
schema. It defines the business vocabulary — the objects that appear in business conversations,
policies, contracts, and decisions.

---

## What a Business Object Is (and Isn't)

| ✅ Business Object | ❌ Not a Business Object |
|---|---|
| A thing the business manages through its lifecycle | A process or activity |
| Named consistently in business conversations | A system or technology |
| Has a lifecycle (created, updated, closed/retired) | A role or organisational unit |
| Can be the subject of a business rule | A capability or function |
| Appears in contracts, reports, or decisions | A project or initiative |

**Examples by domain:**
- Rental property management: Property, Booking, Guest, Tenancy, Maintenance Request
- Financial services: Credit Application, Counterparty, Facility, Collateral, Payment
- Insurance: Policy, Claim, Premium, Insured Party, Risk Assessment
- Retail: Product, Order, Customer, Inventory, Supplier

---

## Object Classification — Choosing a Root Hierarchy

Before classifying objects, present the practitioner with two options. This is
**Classification Checkpoint 0** — it must happen before any objects are typed.

---

### Classification Checkpoint 0 — Present the hierarchy choice

Present this explanation and options inline:

---

> **Choosing a classification hierarchy**
>
> Every object in the Concept Model needs a root type — a category that tells us what *kind*
> of thing it is. Two approaches are available:
>
> ---
>
> **Option A — Capsicum Triad: Party / Record / Resource**
>
> A principled three-type reduction grounded in the Capsicum Framework, consistent with
> ideas from REA (Resources, Events, Agents — McCarthy 1982) and Bunge's ontology for
> information systems. Every business object is one of:
>
> | Type | Definition | Instinct test |
> |------|------------|---------------|
> | **Party** | A person or organisation that acts, consents, or is held accountable | "Who?" |
> | **Record** | Something that documents the state of the world — created when things happen | "What was created to capture this?" |
> | **Resource** | Something of value that is transacted, consumed, or exchanged between parties | "What is actually changing hands?" |
>
> The key clarifying question the triad forces: *"What is the Resource in this interaction?"*
> — i.e. what is the object of the transaction, as opposed to the Party who is its subject.
> This is often the hardest and most clarifying question in business modelling.
>
> Examples for a rental property platform:
> - **Party** — Guest, Owner, Contractor, Tenant
> - **Resource** — Property, Booking, Tenancy (the things being transacted or consumed)
> - **Record** — Financial Report, Maintenance Request, Guest Review, Compliance Obligation
>   (the things created to document what happened)
>
> *Why Resource, not Product or Asset?* "Product" implies physical goods. "Asset" implies
> ownership and balance-sheet thinking. "Resource" is deliberately neutral — it covers
> physical things, services, rights, time, and information equally, which is what makes it
> work across domains as different as healthcare, finance, and property management.
>
> ---
>
> **Option B — Custom hierarchy**
>
> Define root types that fit this domain naturally. PlausibleBA will suggest candidates based
> on the domain, but you own the taxonomy — no external framework is imposed.
>
> Common starting points by domain:
> - Financial services: Instrument / Party / Obligation / Event
> - Healthcare: Patient / Clinical Object / Administrative Record / Encounter
> - Insurance: Policy / Claim / Party / Risk
> - Retail / supply chain: Product / Order / Party / Inventory
> - Government: Citizen / Service / Entitlement / Case
>
> Custom hierarchies work well when the domain has strong existing vocabulary that
> practitioners already use consistently, or when the Capsicum triad would require
> too much explanation to the intended audience of the artefact.
>
> ---
>
> **Which should you choose?**
> - Choose **Option A** if you want a framework that works consistently across domains,
>   cross-validates well with capability maps, and connects to established business
>   architecture thinking (REA, TOGAF, Capsicum).
> - Choose **Option B** if domain-specific vocabulary is more important than cross-domain
>   consistency, or if the artefact audience won't engage with an abstract framework.

---

Present both options clearly and **wait for the practitioner to choose before proceeding.**
Record the chosen hierarchy — it governs all subsequent classification and appears in the
XLSX Legend.

If Option A is chosen, use Party / Record / Resource throughout.
If Option B is chosen, agree the custom types before classifying any objects.

---

### Capsicum Triad — detailed classification guide (Option A)

**Party**
Any person, organisation, or role that acts, consents, holds obligations, or is held
accountable. Parties have identity, relationships, and agency.
- Signals: appears in contracts as a signatory; has rights or obligations; can initiate
  or block a transaction
- Examples: Guest, Owner, Contractor, Tenant, Regulator, Insured, Borrower

**Resource**
Something of value that is transacted, allocated, consumed, or exchanged between parties.
The Resource is the *object* of the interaction — what the interaction is *about*.
Resources have value, can be transferred, and change hands or state through transactions.
- Signals: appears in the subject line of a contract ("for the lease of [Property]");
  the answer to "what is being exchanged here?"; has a value the business can increase,
  protect, or realise
- Examples: Property, Portfolio, Booking (the reservation right), Tenancy (the lease right)
- Common confusion: Financial Report looks like a Resource but is a Record — it documents
  the state of Resources, it is not itself transacted

**Record**
Something created to document that a business event occurred, a decision was made, or a
state was measured. Records are evidence — they capture what happened to Parties and
Resources. They are not transacted; they are produced.
- Signals: created *as a result of* something happening; answers "what did we create to
  capture this?"; has an author, a timestamp, and a status lifecycle
- Examples: Financial Report, Maintenance Request, Guest Review, Compliance Obligation,
  Invoice, Assessment, Audit Log

**The triad in practice — PortfolioProp example:**

| Object | Type | Reasoning |
|--------|------|-----------|
| Guest | Party | Acts, consents, holds booking obligations |
| Owner | Party | Holds the management agreement, receives income |
| Contractor | Party | Provides services under contract |
| Property | Resource | The thing being transacted — leased, occupied, managed |
| Portfolio | Resource | Aggregate of Resources under management |
| Booking | Resource | The reservation right being exchanged between Guest and platform |
| Tenancy | Resource | The occupancy right exchanged between Owner and Tenant |
| Financial Report | Record | Documents the financial state of Resources |
| Maintenance Request | Record | Documents that a maintenance event occurred and needs resolution |
| Guest Review | Record | Documents a Guest's assessment of their stay |
| Compliance Obligation | Record | Documents a regulatory requirement that must be met |
| Yield Performance | Record | Documents measured performance of a Resource |
| Subscription/Fee | Record | Documents the fee agreement — but NOTE: the *right* to the fee is a Resource |

---

## Relationship Classification

Relationships between objects use three types:

| Relationship | Meaning | Notation |
|---|---|---|
| **Association** | Objects are related in the business domain | A — B |
| **Composition** | One object is made up of another (lifecycle dependency) | A ◆— B |
| **Generalisation** | One object is a specialisation of another | A ◁— B |

Keep relationships at business level — avoid technical foreign-key thinking.

---

## Elicitation Process

> ⚠️ **Always run this skill in a fresh Cowork task.** Prior conversation context will cause Claude to reference previous outputs rather than eliciting from the current input. Open a new task, paste the business description, then type the slash command.

### Step 1 — Establish Scope
Identify from input or by asking:
- What **business domain** does this cover?
- Is there an existing **Capability Map** to cross-validate against?
- Are there existing **glossaries, data dictionaries, or system entity lists** to review?

### Step 2 — Classification Checkpoint 0: choose the root hierarchy
Present the Party / Record / Resource triad (Option A) versus a custom hierarchy (Option B)
as described in the Object Classification section above.

**Do not classify any objects until the practitioner has chosen.**

### Step 3 — Identify Objects
Mine the input for nouns that the business consistently manages. Signals:
- Nouns that appear repeatedly in business conversations
- Things that are created, tracked, updated, and retired
- Things that appear in reports, contracts, or decisions
- Things that ground L3 capabilities in the Capability Map

Aim for 8–20 objects for a single business domain. More than 25 suggests scope creep or
conflation of two domains.

### Step 4 — Classify Each Object
Using the chosen hierarchy, assign each object a root type and write a one-sentence
business definition: *"A [type] that [what it is / what lifecycle it has]."*

If Option A (Capsicum Triad): apply the Party / Record / Resource guide above.
If Option B (Custom): apply the agreed domain-specific types.

The key diagnostic question for the triad: *"Is this the thing being exchanged, or the
thing created to document the exchange?"* — if the former, it is a Resource; if the latter,
it is a Record.

### Step 5 — Identify Relationships
For each object pair that has a meaningful business relationship, name the relationship and
classify it (Association, Composition, Generalisation).

Keep to relationships that a business stakeholder would recognise and care about. Avoid
technical or implementation-level relationships.

### Step 6 — Cross-validate Against Capability Map (if available)

This is the primary quality check:

**Object → Capability check:** Does every object have at least one L3 capability that manages it?
Objects with no corresponding capability are **coverage gaps** — either a capability is missing
from the map, or the object is out of scope.

**Capability → Object check:** Does every L3 capability reference an object in the Concept Model?
Capabilities with no grounding object are **orphaned capabilities** — either the object needs
naming, or the capability is a process step masquerading as a capability.

Produce a cross-reference table as part of the validation output.

### Step 7 — Checkpoint: pause for validation

Present the Object Register inline and ask:

> *"Here is a draft Concept Model showing the core objects this business manages, classified
> using [chosen hierarchy]. Do these reflect the things your business teams talk about? Any
> objects missing, or any that feel like they belong inside another?"*

**Do not generate the XLSX until confirmed or adjusted.**

---

### Step 8 — Render the interactive concept graph (PRIMARY deliverable)

Immediately after the Object Register is validated, render an interactive concept graph as a self-contained HTML artifact. Do NOT wait for the user to ask. Do NOT generate the XLSX first. The graph IS the deliverable — XLSX is a download option offered beneath it.

**Visual design — match VCC exactly:**
- Page background: `#0f172a`; SVG canvas: `background:#111827`, `border:1px solid #1e293b`
- Party nodes: circle r=28, `fill:rgba(45,212,191,0.12)`, `stroke:rgba(45,212,191,0.5)`, label `color:#ccfbf1`
- Resource nodes: circle r=28, `fill:rgba(59,130,246,0.12)`, `stroke:rgba(59,130,246,0.5)`, label `color:#bfdbfe`
- Record nodes: rounded rect 72×36 rx=5, `fill:rgba(236,72,153,0.12)`, `stroke:rgba(236,72,153,0.5)`, label `color:#fce7f3`
- **Icons inside nodes** (small, 50% opacity, same color as node stroke):
  - Party: person silhouette (circle head + body arc)
  - Resource: plus-in-square icon
  - Record: document lines icon
- Edge lines: `stroke-dasharray:4 3`, `stroke:rgba(30,41,59,0.9)`, `stroke-width:1`
- Selected node: `stroke-width:3`
- Column labels at top: Party / Resource / Record in `font-size:9px`, `font-weight:700`, uppercase, matching node color
- **Graph/Table tab toggle** above legend (Graph tab active)
- Font: `'DM Sans', system-ui, sans-serif`

**Detail panel (click to reveal — matches VCC):**
- `background:#1e293b`, `border:1.5px solid [node color]`, `border-radius:8px`
- Object name: `font-size:15px`, `font-weight:700`, `color:#f1f5f9`
- Type badge: `font-size:10px`, `font-weight:700`, `text-transform:uppercase`, `letter-spacing:0.5px`, color matches node
- Definition: `font-size:12px`, `color:#94a3b8`, `line-height:1.55`
- Lifecycle label: `font-size:9px`, `font-weight:700`, `text-transform:uppercase`, `color:#94a3b8`
- **Lifecycle pills** (not plain text): each state as `background:rgba(255,255,255,0.09)`, `color:#cbd5e1`, `border:1px solid rgba(255,255,255,0.14)`, `border-radius:4px`, `padding:3px 10px`, `font-size:10px`
- NO attributes table — that is VCC-only territory

Layout: Party nodes left column (~x:90), Resource nodes centre (~x:290), Record nodes split right (~x:530 and ~x:660). Space vertically by count. Draw dashed edges between related objects.

Build all node and edge data from the Object Register confirmed in this session. Do NOT use PortfolioProp example data.

**Footer (required on every rendered artifact):**
Include a footer row at the bottom of the artifact, styled `font-size:10px; color:#94a3b8; padding:10px 0 2px; border-top:1px solid #2e3f5c; margin-top:12px`:
```
Generated by the PlausibleBA Skills Library | www.plausibleba.com
Turn this into an interactive workshopping canvas → plausibleba.com/canvas
```
First line in `color:#94a3b8`, second line in `color:#4a9eda` with the URL as a link.

After rendering the graph, **immediately generate both export files** without waiting for the user to ask:

1. **XLSX** — the full 4-tab workbook (Concept Model Summary, Object Register, Validation Summary, Legend) following the XLSX Output Structure below. Save to the workspace folder as `<organisation>_concept_model.xlsx`.
2. **JSON** — the VCC pipeline format following the JSON Schema below. Save to the workspace folder as `<organisation>_concept_model.json`.

Use the `present_files` MCP tool (if available) to surface the files to the user after saving.

Then present the deliverables and next steps with clickable links:

> *"Here is your concept model. Click any node to see its definition and lifecycle states.*
>
> **Downloads:**
> - *[View Concept Model XLSX](computer:///<workspace_path>/<organisation>_concept_model.xlsx) — Object Register workbook (4 tabs)*
> - *[View Concept Model JSON](computer:///<workspace_path>/<organisation>_concept_model.json) — VCC pipeline format*
>
> **Build the full business architecture stack:**
> - *Type `/capability-map` to produce or refine the **Capability Map** — cross-validates that every object has at least one grounding capability*
> - *Type `/value-stream` to map **Value Streams** — trace how these business objects flow through staged delivery sequences*
> - *[Open in PlausibleBA Canvas](https://www.plausibleba.com/canvas) — upload the JSON for full interactive visualisation"*

Replace `<workspace_path>` with the actual workspace output path and `<organisation>` with the client/organisation name from this session (snake_case for filenames).

---

## Inline Preview Format

**Classification Checkpoint 0 — hierarchy choice (present before any classification):**

> *"Before we classify the objects, which hierarchy would you like to use?*
> *Option A — Capsicum Triad (Party / Record / Resource): principled, cross-domain consistent,*
> *grounded in REA and Bunge. Recommended for business architecture work.*
> *Option B — Custom hierarchy: domain-specific types you define.*
> *[See the Object Classification section above for full explanation of each option.]*"

---

**Checkpoint — Object Register preview (sorted by Number, after hierarchy chosen):**

| Number | Type | Name | Definition | Related Capabilities |
|--------|------|------|------------|---------------------|
| 1 | Resource | Property | A Resource that is leased, occupied, and managed on behalf of an owner | 2.1.1, 2.1.2, 2.1.3 |
| 2 | Party | Guest | A Party who makes or holds a confirmed short-stay booking | 3.2.1, 3.3.1 |
| 3 | Record | Financial Report | A Record that documents income, expenses and net return for a property | 6.2.1, 6.2.3 |

---

## XLSX Output Structure

Four worksheets, following the PlausibleBA taxonomy standard tab order.

**Sheet 1: Concept Model Summary**
- Title block, subtitle, branding line
- Chosen hierarchy: Capsicum Triad (Party / Record / Resource) or custom type names
- Totals: Objects by root type
- Per-type breakdown table
- Cross-validation summary: objects with full coverage / gaps / orphaned capabilities
- Notes on key modelling decisions, including any non-obvious classifications
- Next Steps: Value Stream Analysis

**Sheet 2: Object Register**

Branding line above header. Pre-sorted by Number.

| # | Column | Description |
|---|--------|-------------|
| 1 | **Number** | Taxonomy position — primary sort key |
| 2 | **Type** | Root type from chosen hierarchy (e.g. Party / Record / Resource) |
| 3 | **Name** | Object name (noun, singular) |
| 4 | **Definition** | "A [type] that [lifecycle / what it is]" |
| 5 | **Lifecycle States** | Key states: e.g. Enquiry → Confirmed → Completed → Archived |
| 6 | **Related Capabilities** | Comma-separated capability numbers from the Capability Map |
| 7 | **Related Objects** | Key relationships (name + relationship type) |
| 8 | ID | `obj_<snake_case_name>` |

**Sheet 3: Validation Summary**

| Check | Result | Notes |
|-------|--------|-------|
| Hierarchy chosen and recorded | PASS/FAIL | |
| All objects have a Type from the chosen hierarchy | PASS/FAIL | |
| All objects have a business definition | PASS/FAIL | |
| All objects have at least one related capability | PASS/NOTE | |
| All L3 capabilities reference a named object | PASS/NOTE | |
| Object count within 8–20 | PASS/NOTE | |
| No duplicate semantics across objects | PASS/FAIL | |
| No process steps masquerading as objects | PASS/FAIL | |
| Relationships are business-level, not technical | PASS/FAIL | |
| (If Capsicum Triad) Resource/Record distinction is defensible | PASS/NOTE | |

**Sheet 4: Legend**
Chosen hierarchy with full type definitions, Capsicum Framework reference (if Option A),
relationship types, colour coding, PlausibleBA standard version, website link.

If Option A was chosen, include in the Legend:

> *"Object types follow the Capsicum Framework Party / Record / Resource triad — consistent
> with REA (Resources, Events, Agents — McCarthy 1982) and Bunge's ontology for information
> systems. Party = who acts. Resource = what is transacted. Record = what documents the
> transaction."*

---

## XLSX Colour Coding

| Fill | Hex | Usage |
|------|-----|-------|
| Dark blue `#1F3864` | Header rows | |
| Teal `#D6E4F0` with `#1F3864` text | Party rows | |
| Mid blue `#BDD7EE` with `#1F4E79` text | Resource rows | |
| Green `#E2EFDA` with `#375623` text | Record rows | |
| (Custom type) | Practitioner-defined | When Option B is chosen |

Note: when a custom hierarchy has more than three types, extend the colour palette
consistently — use the PlausibleBA blue/green/teal range and avoid red (reserved for
validation failures).

---

## JSON Schema (for VCC pipeline integration)

```json
{
  "obj_<snake_case_name>": {
    "id": "obj_<snake_case_name>",
    "elementType": "BusinessObject",
    "name": "<Object Name>",
    "number": "1",
    "classificationHierarchy": "CapsicumTriad|Custom",
    "type": "Party|Record|Resource|<custom>",
    "definition": "A [type] that ...",
    "lifecycleStates": ["state1", "state2"],
    "relatedCapabilities": ["cap_id_1", "cap_id_2"],
    "relatedObjects": [
      {
        "objectId": "obj_other",
        "relationship": "Association|Composition|Generalisation",
        "label": "has many"
      }
    ]
  }
}
```

---

## Quality Bars

A good Concept Model for a single business domain:
- 8–20 named objects
- Every object has a Type and a one-sentence business definition
- Every object has at least one lifecycle state sequence
- Every object is referenced by at least one L3 capability (if a Capability Map exists)
- No two objects are semantically identical at the same level
- Relationships are named and typed

---

## Common Failure Modes

| Failure | Example | Fix |
|---------|---------|-----|
| Process step as object | "Onboarding" | → "Property" (the thing being onboarded) |
| System as object | "Airbnb" | → "Booking" or "Channel" (what the system manages) |
| Too granular | "Airbnb Booking", "Vrbo Booking" | → "Booking" (generalise; channel is an attribute) |
| Duplicate semantics | "Guest" and "Tenant" as separate top-level objects | → Decide: generalise to "Occupant" or keep distinct with clear definitions |
| Missing object | Capability references "Financial Report" but no such object defined | → Add "Financial Report" to the register |

---

## Next Steps

Next steps are now presented inline with the downloads after the concept graph is rendered (see Step 8).
The `/capability-map` and `/value-stream` commands are offered as clickable follow-on actions,
and the XLSX/JSON exports are generated automatically — there is no separate export gate.