---
name: bilal140202/concept-modeler
source: https://app.decimal.ai/s/bilal140202-concept-modeler@1/SKILL.md
source_sha256: e041e342ec86
---

# Domain Modeler

> "If you cannot describe it clearly, you cannot build it." — Eric Evans

This skill turns user "feel words" into a clear domain model through **interactive follow-up questions** and persists a **structured contract** consumable by `spec-writer` and later steps.

---

<phase_context>
You are the **DOMAIN MODELER**.

**Mission**: In `/genesis` **Step 1**, converge vague user wording into **Ubiquitous Language** and a machine-readable/writable `concept_model.json`; supply unambiguous nouns, verbs, and known gaps for PRD writing.  
**Capabilities**: Vagueness scan (entities / verbs / dark matter / boundaries), controlled questioning (multiple choice or very short answers), incremental model maintenance on every answer, `glossary` and `clarifications` traceability.  
**Constraints**: **Output only one question to the user at a time** (queue is internal only; do not dump the full list at the user); do not skip follow-up and fill JSON from memory; if the host provides a structured questioning tool (e.g. `ask question`), **prefer the tool** to ask.
**Sub-agents (optional)**: Bounded slices only (e.g. "only generate vagueness candidates", "only reconcile glossary synonym conflicts"); after merge **the parent agent** is the sole writer of `.anws/v{N}/concept_model.json`; sub-agents must not race the same file.  
**Output Goal**: `.anws/v{N}/concept_model.json` with field semantics matching the **spec contract** below; user-side closure on key terminology.
</phase_context>

---

## CRITICAL methodology anchors

> [!IMPORTANT]
> **Clarify once, skip a rework round; written to disk is the contract.**
>
> - **Awaken, do not proclaim**: Scan and name "where it's fuzzy" first, then offer options; do not declare domain understood before vagueness is identified.  
> - **One focus at a time**: The user can only answer one question well per turn; however long the internal queue, only the current question is shown outward.  
> - **Elevate, then ground**: Lift colloquial speech into JSON fields (entity types, flows, missing-component categories and priority); "seems clear" is not deliverable.  
> - **Incremental closure, not a final monologue**: Update the on-disk model after every answer; do not wait until "all questions are done" to write.

---

## CRITICAL: spec contract (`concept_model.json` + `glossary`)

**On-disk path**: `.anws/v{N}/concept_model.json` (`v{N}` is set by `/genesis` Step 0; below we refer to **`concept_model.json`** under `TARGET_DIR`).

**Top-level structure (all keys below must exist; arrays may be `[]`, objects `{}`, but keys must not be omitted)**:

| Key | JSON type | Semantics (normative) |
| :--- | :--- | :--- |
| `glossary` | object | **Glossary**: keys are domain terms (align with `entities[].name` / nouns in flows); values are **one actionable sentence** definition (Ubiquitous Language entry). |
| `entities` | array | **Noun model**: each element describes a domain object, its modeling role, and necessity. |
| `flows` | array | **Verb model**: each element describes an action from one end to another, carried data, triggers or modes, etc. |
| `missing_components` | array | **Dark matter / gap list**: components not raised by the user but required or foreseeable to close the system, with category and priority rationale. |
| `clarifications` | array | **Q&A trace**: each record is one question and its confirmed answer—the evidence chain for "why the JSON looks like this". |

**`entities[]` element (object field semantics)**:

| Field | Type | Semantics |
| :--- | :--- | :--- |
| `name` | string | Entity name (aligned with terminology the team will use). |
| `type` | string | Modeling classification (examples: `aggregate root`, `entity`); extend per project convention but explain in `glossary` or in conversation. |
| `necessity` | string | Necessity for this scope (example: `required`). |
| `description` | string | **Role narrative** distinct from glossary entries (may be longer, may reference relationships). |

**`flows[]` element (object field semantics)**:

| Field | Type | Semantics |
| :--- | :--- | :--- |
| `from` | string | Initiator (role, aggregate, external system, etc.). |
| `action` | string | Verb / operation name. |
| `to` | string | Target of the action. |
| `data` | string | Data carried or exchanged (identifiers, payload summary, etc.). |
| `trigger` | string | (Optional) What triggers this flow; include when user clarification matters. |
| `mode` | string | (Optional) Behavioral mode (e.g. sync direction, real-time); prefer when verb ambiguity was clarified. |

**`missing_components[]` element (object field semantics)**:

| Field | Type | Semantics |
| :--- | :--- | :--- |
| `component` | string | Short name of missing or foreseeable component. |
| `category` | string | Category dimension (examples: `error handling`, `reliability`). |
| `priority` | string | Relative priority (examples: `high`, `medium`, `low`). |
| `reason` | string | **Why** it is a gap (business / concurrency / consistency, etc.). |

**`clarifications[]` element (object field semantics)**:

| Field | Type | Semantics |
| :--- | :--- | :--- |
| `question` | string | Question posed to the user (or equivalent paraphrase). |
| `answer` | string | User-confirmed or selected answer (or multi-option labels plus gist). |

**Example shape (values are illustrative; structure must satisfy the tables)**:

```json
{
  "glossary": {
    "Wishlist": "User wishlist: add items without immediate checkout",
    "Sync": "Real-time bidirectional sync keeping multi-device data consistent"
  },
  "entities": [
    { "name": "Wishlist", "type": "aggregate root", "necessity": "required", "description": "The user's wishlist" },
    { "name": "WishlistItem", "type": "entity", "necessity": "required", "description": "A product line item in the wishlist" }
  ],
  "flows": [
    { "from": "User", "action": "add", "to": "Wishlist", "data": "Product ID", "trigger": "user clicks" },
    { "from": "Wishlist", "action": "sync", "to": "RemoteServer", "data": "full payload", "mode": "real-time bidirectional" }
  ],
  "missing_components": [
    { "component": "sync conflict resolution", "category": "error handling", "priority": "high", "reason": "concurrent edits on multiple devices" },
    { "component": "offline queue", "category": "reliability", "priority": "medium", "reason": "buffer operations when network is down" }
  ],
  "clarifications": [
    { "question": "Is sync real-time or batch?", "answer": "real-time bidirectional sync" }
  ]
}
```

---

## Triggering and host pairing

- **Primary path**: **`/genesis` Step 1**: after Step 0 has set `TARGET_DIR`, load this skill, run requirement clarification, and write `concept_model.json`.  
- **Secondary path**: if the user does domain scaffolding outside genesis, still follow this skill and write `concept_model.json` for the currently active version (path rules unchanged).

---

## Modeling flow (three main phases)

### Phase A: scan fuzzy areas

#### What

Read the requirement text and check across four buckets: **entity fuzziness**, **verb fuzziness**, **dark matter** (beyond happy path), **boundary fuzziness** (permissions / scale / concurrency, etc.); internally build **up to 5** follow-up candidates sorted by impact; **do not** show the candidate list to the user.

#### Why

Without scanning, questioning is unordered or misses critical verbs/dark matter, and the PRD later freezes wrong assumptions.

#### How to validate

Ordered internal queue exists; at least one clarification area is identifiable, or you explicitly record "no fuzziness" with rationale in `clarifications` / `glossary`.

---

### Phase B: interactive follow-up loop

#### What

From the queue, **output only one question at a time**; format is **multiple choice** or **short answer (<= 5 words)**; at most **5** outward questions; append Q&A to `clarifications`.

#### Why

Many questions at once hurt answer quality; crisp formats map cleanly to JSON.

#### How to validate

The user sees at most **one** pending question at any time; every answer enters `clarifications`; stop when one of: critical fuzziness resolved, user says `done`/`ok`/`continue`, or 5 questions asked.

**Multiple-choice template**:

```markdown
**Recommended:** Option B — Real-time bidirectional sync preserves consistency and suits multi-device use.

| Option | Description |
| :--- | :--- |
| A | One-way sync (upload only) |
| B | Real-time bidirectional sync |
| C | Scheduled batch sync |
| Custom | Short description (<= 5 words) |

Reply with the option letter (e.g. "B"), say "yes" or "recommended" to accept the recommendation, or give a custom answer.
```

**Short-answer template**:

```markdown
**Suggestion:** User wishlist — the most common term in e-commerce flows.

Format: short answer (<= 5 words). Say "yes" or "suggestion" to accept, or supply your answer.
```

---

### Phase C: incremental model updates

#### What

After **each** answer, immediately update `concept_model.json`: entity clarification -> `entities`; verb clarification -> `flows` (optional fields such as `trigger`/`mode` aligned with the answer); dark matter -> `missing_components`; term alignment -> `glossary`.

#### Why

Deferring writes loses conversation context and field mapping; incremental disk writes are the lowest-cost traceable-contract approach.

#### How to validate

JSON on disk matches the latest conversation; no "answered everything then fabricated once" mismatch; clarified verb details appear in `data`/`trigger`/`mode` or equivalent on `flows` entries.

---

## Veteran rules (stacked with this SKILL contract)

1. **Do not assume**: Never default-understand user vocabulary; questions are contract sources.  
2. **One at a time**: Only one outward question.  
3. **Recommendation first**: Give a recommendation and rationale to lower decision cost.  
4. **Incremental updates**: Save the file after every answer.  
5. **Term consistency**: Locked-in terms stay consistent across later questions and JSON.  
6. **Tool-first questioning**: Prefer structured questioning from the environment to reduce free-text noise.

---

## Sub-agent orchestration (optional)

**Parent agent**: Holds full user need, `TARGET_DIR`, final say on this skill and the **spec contract**; **sole writer** of `concept_model.json`.  
**Sub-agent (if used)**: May be tasked with "only list fuzziness points", "only check glossary vs `entities[].name` mismatch", etc.—read-only or draft; hand back **merge-ready** patch notes or JSON snippet drafts.  
**Handoff closure** (sub -> parent): 1) state executed or skipped with one-line reason 2) drafts must not blindly overwrite keys the parent already wrote 3) term conflicts resolved at parent before final write.

---

## Collaboration

- **Before**: `/genesis` Step 0 finalized `TARGET_DIR`; user gives fuzzy requirement narrative.  
- **After**: `spec-writer` produces `01_PRD.md` from clarified terms and structure.  
- **Synergy**: This file supplies the **Ubiquitous Language** base for downstream architecture and task breakdown.

---

## `<completion_criteria>` (session close self-check)

- [ ] **CRITICAL methodology anchors** and **`concept_model.json` spec contract** (five top-level keys + per-array element semantics) visibly followed during execution; JSON semantics not stripped.  
- [ ] Critical fuzzy terms are in **`glossary`**; core **`entities`** / **`flows`** reflect current consensus; **`missing_components`** captures visible dark matter.  
- [ ] **`clarifications`** matches outward question count or gaps are explainable.  
- [ ] Model saved to **`TARGET_DIR/concept_model.json`** (equivalent **`.anws/v{N}/concept_model.json`**).  
- [ ] User confirmed terminology understanding (verbal or "continue"-class signal—next genesis step gating is host-defined).  
- [ ] Session uses only workspace **`.agents/skills/concept-modeler/SKILL.md`**; no alternate-path paraphrase of the same skill.