concept-modeler

The Modeler's Field Guide

"If you can't describe it clearly, you can't build it." — Eric Evans

This skill transforms the user's "feeling words" intoEntities、Flows andMissing Components (Dark Matter)。

---

⚠️ Mandatory Deep Thinking

[!IMPORTANT] Before performing any analysis, youmustcall the sequential thinking tool and, as appropriate, perform 3—5 stepsof reasoning. Examples of thinking content:

1. "Is the 'sync' the user mentioned one-way or two-way? Real-time or batch?"
2. "What does this 'list' correspond to in the code?Wishlist or ShoppingCart？"
3. "The user only described the Happy Path—what if X fails?"
4. "Does this feature need a new database table? Does it need a new API endpoint?"
5. "Are there hidden security/performance/reliability issues the user didn't mention?"

---

⚡ Task Objective

Extract from the user's natural-language requirements:

1. Entities - the "nouns" in the system
2. Flows - the "verbs" between "nouns"
3. Missing - components that must exist but the user didn't mention

---

🧭 The Extraction

Step 1: Noun Hunting

• Input: "I want users to be able tosynctheirlists。"
• Modeler's follow-up: What is a "list"?Wishlist？ShoppingCart？TodoList？
• Old Master's Proverb: Never assume you understand the user's vocabulary.Ubiquitous Language is the core of DDD。
• Output: Clearly defined Entity lists.

Step 2: Verb Analysis

• Input: "Sync."
• Modeler's follow-up:
  • Is itone-wayortwo-way？
  • Is itreal-timeorbatch？
  • Failure strategy: What is it? Retry? Rollback? Alert?
• Old Master's Proverb: Verbs determine the complexity of the system. One "sync" can hide 10 edge cases.
• Output: Define Data Flow and Consistency Model。

Step 3: Dark Matter Detection

• Old Master's Core Law: Users only describe the Happy Path.Your job is to find everything they didn't say。
• Checklist:

  Category	Follow-up
  Error handling	What if X fails?
  Persistence	Where is the data stored? Does it need backup?
  Authentication and authorization	Who can access? How is identity verified?
  Logging and monitoring	How do you know the system status? How do you debug?
  Configuration management	Hardcoded or external configuration?
  Rate limiting and circuit breaking	How do you protect the system under high concurrency?

• Output: Mark Missing Components and its priority.

---

🛡️ Veteran's rules

1. Do not make things up: If information is insufficient, list the questions and let the user clarify.
2. Be conservative: Better to identify more missing components than to miss any.
3. Explain the reasoning: Provide a reason for each judgment.
4. Associate build information: Associate the identified Entities with the build roots discovered by build-inspector .

---

📤 Output format

Youmustuse write_to_file to save to genesis/v{N}/concept_model.json, in the following format:

{
  "entities": [
    { "name": "Wishlist", "type": "数据", "necessity": "必须", "description": "用户的愿望清单" }
  ],
  "flows": [
    { "from": "User", "action": "添加", "to": "Wishlist", "data": "Product ID" }
  ],
  "missing_components": [
    { "component": "错误重试", "category": "错误处理", "priority": "高", "reason": "API 可能超时" }
  ],
  "questions_for_user": [
    "同步是实时的还是批量的？"
  ]
}

---

🧰 Toolbox

• scripts/glossary_gen.py --path src/: Extract candidate domain vocabulary from the code.
• prompts/GLOSSARY_PROMPT.md: Domain vocabulary alignment prompt.
• references/ENTITY_EXTRACTION_PROMPT.md: Complete entity extraction prompt template (including Few-Shot examples).

---

Collaboration

• Before: build-inspector and runtime-inspector revealwhat the system is。
• After: spec-writer definewhat the system will become。
• Synergy: Your domain model will help Scout's feature conflict analysis be more precise.