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.
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.
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):
{
"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:
/genesisStep 1: after Step 0 has setTARGET_DIR, load this skill, run requirement clarification, and writeconcept_model.json. - Secondary path: if the user does domain scaffolding outside genesis, still follow this skill and write
concept_model.jsonfor 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:
**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:
**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)
- Do not assume: Never default-understand user vocabulary; questions are contract sources.
- One at a time: Only one outward question.
- Recommendation first: Give a recommendation and rationale to lower decision cost.
- Incremental updates: Save the file after every answer.
- Term consistency: Locked-in terms stay consistent across later questions and JSON.
- 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:
/genesisStep 0 finalizedTARGET_DIR; user gives fuzzy requirement narrative. - After:
spec-writerproduces01_PRD.mdfrom 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.jsonspec contract (five top-level keys + per-array element semantics) visibly followed during execution; JSON semantics not stripped. - Critical fuzzy terms are in
glossary; coreentities/flowsreflect current consensus;missing_componentscaptures visible dark matter. -
clarificationsmatches 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.
