domain-knowledge

# Domain Knowledge Documentation ## Overview This skill helps document domain knowledge systematically. It captures entities, relationships, processes, and terminology to create a shared understanding of the domain. **Purpose**: Build a comprehensive domain model that serves as the foundation for requirements, implementation, and team communication. ## CRITICAL: NO ASSUMPTIONS POLICY **This skill MUST trigger dialogue with users, NOT make assumptions about the domain.** AI has a strong tendency to: - Invent entity attributes when they're not specified - Make up relationships between entities - Fabricate process steps and business logic - Assume data types and validation rules - Create plausible but incorrect domain terminology **NEVER do any of the above.** Instead: - **ASK questions** about every entity attribute - **WAIT for answers** before documenting relationships - **DOCUMENT gaps** with `# TODO:` or `# QUESTION:` if user doesn't know - **VERIFY understanding** before creating documentation - **STOP immediately** when uncertain about ANY detail ### What to Always Ask - "What attributes does this entity have?" - "What's the data type of each attribute?" - "How does this entity relate to [other entity]?" - "What's the cardinality of this relationship?" (1:1, 1:N, N:M) - "What are the steps in this process?" - "Are there validation rules or constraints?" - "Can you provide a real example from your domain?" ## File Location and Organization ### Directory Structure Domain knowledge is organized in `docs/domains/[domain-name]/[subdomain-name]/` with subdirectories for each type: ``` docs/domains/ └── [domain-name]/ └── [subdomain-name]/ ├── entities/ │ ├── _overview.md (Master ERD with all entities) │ ├── customer.md (Individual entity file) │ └── order.md ├── processes/ │ ├── _overview.md (Process relationships and flow) │ ├── checkout.md (Individual process file) │ └── fulfillment.md └── glossary/ ├── _overview.md (Alphabetical index of all terms) ├── sku.md (Individual term file) └── backorder.md ``` **File organization:** - **entities/** - One file per entity, plus `_overview.md` with master ERD - **processes/** - One file per process, plus `_overview.md` showing relationships - **glossary/** - One file per term/concept, plus `_overview.md` as index ### File Naming - Use **kebab-case** for filenames: `order-item.md`, `user-registration.md` - Use `_overview.md` for index/summary files in each subdirectory - Keep names concise and domain-specific ## Core Capabilities ### 1. Document Entities Capture domain entities - the core concepts and objects in the domain. **Entity documentation includes:** - **Name** - What the entity is called - **Description** - What it represents in the domain - **Attributes** - Properties and data the entity holds - **Constraints** - Business rules and validation - **Lifecycle** - States and transitions - **Relationships** - Connections to other entities **Template:** ```markdown # [Entity Name] **Description**: [What this entity represents] ## Attributes | Attribute | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Unique identifier | | name | string | Yes | ... | ## Relationships - **has-many** [Other Entity] - Description - **belongs-to** [Other Entity] - Description ## Lifecycle - Created when: [trigger/event] - Status transitions: [state changes] - Deleted when: [condition] ## Business Rules - [Rule 1] - [Rule 2] ## Example ```json { "id": "123", "name": "Example" } ``` ``` ### 2. Document Relationships Capture how entities connect and interact. **Relationship types:** - **One-to-One** (1:1) - Each A has exactly one B - **One-to-Many** (1:N) - Each A has many B - **Many-to-Many** (N:M) - Many A relate to many B - **Composition** - Part-of relationships (strong ownership) - **Aggregation** - Has-a relationships (weak ownership) **Template:** ```markdown ## [Entity A] → [Entity B] **Type**: one-to-many | many-to-many | one-to-one **Description**: [What this relationship means] **Cardinality**: - [Entity A]: 0..1 | 1 | 0..* | 1..* - [Entity B]: 0..1 | 1 | 0..* | 1..* **Constraints**: - [Business rules for this relationship] ``` ### 3. Visualize with Mermaid Diagrams #### Entity Relationship Diagrams (ERD) ```markdown ## Entity Relationship Diagram \`\`\`mermaid erDiagram Customer ||--o{ Order : "places" Order ||--|{ OrderItem : "contains" Product ||--o{ OrderItem : "included in" Customer { string id PK string name string email } Order { string id PK string customer_id FK date order_date string status } \`\`\` ``` **Relationship notation:** - `||--||` : One-to-one - `||--o{` : One-to-many - `}o--o{` : Many-to-many #### Process Flow Diagrams ```markdown ## Process Flow \`\`\`mermaid flowchart TD Start([Customer initiates checkout]) Start --> Validate{Cart valid?} Validate -->|No| Error[Show error] Validate -->|Yes| Payment[Process payment] Payment --> Confirm[Send confirmation] Confirm --> End([Complete]) \`\`\` ``` #### State Diagrams ```markdown ## Order Lifecycle \`\`\`mermaid stateDiagram-v2 [*] --> Pending : Order placed Pending --> Confirmed : Payment received Confirmed --> Shipped : Items dispatched Shipped --> Delivered : Customer receives Delivered --> [*] Pending --> Cancelled : Customer cancels Cancelled --> [*] \`\`\` ``` ### 4. Document Processes Capture business workflows and processes. **Process documentation includes:** - Process name and goal - Trigger (what starts it) - Actors (who participates) - Steps (what happens) - Decision points - Outcomes - Edge cases **Template:** ```markdown # [Process Name] **Goal**: [What this process achieves] **Trigger**: [What starts this process] ## Actors - [Actor 1] - [Their role] - [Actor 2] - [Their role] ## Steps 1. **[Step name]** - Who: [Actor] - What: [Action] - Input: [Required data/state] - Output: [Result/state change] 2. **[Decision point]** - If [condition]: Go to step X - Else: Go to step Y ## Outcomes - Success: [What happens] - Failure: [What happens] ## Business Rules - [Rule 1] - [Rule 2] ## Edge Cases - [Case 1]: [How it's handled] ``` ### 5. Document Ubiquitous Language Capture terms, definitions, and domain vocabulary. **Glossary documentation includes:** - Term name - Definition - Context/usage - Synonyms - Related terms - Examples **Template:** ```markdown # [Term] **Definition**: [Clear, concise definition] **Context**: [When/where this term is used] **Synonyms**: [Alternative terms] **Related terms**: [Connected concepts] **Example**: > [Usage in context] **Technical mapping**: - Database: `table_name.column_name` - Code: `ClassName` or `functionName` ``` ## Discovery Workflow When documenting domain knowledge, follow these steps: 1. **Ask about existing documentation** - "Where do you currently document domain knowledge?" - "Do you have schema files, type definitions, or API docs?" 2. **Start with entities** - "What are the core entities in this domain?" - "Which entity should we document first?" - Document one entity completely before moving to the next 3. **Map relationships** - "How do these entities relate to each other?" - "What's the cardinality of this relationship?" 4. **Document processes** - "What business processes involve these entities?" - "Who are the actors in this process?" 5. **Build glossary** - "What terms does your team use?" - "Are there any ambiguous terms?" ## Best Practices 1. **Start small, grow organically** - Don't try to document everything at once 2. **Keep it current** - Update when domain understanding changes 3. **Use examples liberally** - Concrete examples make concepts clear 4. **Link everything** - Connect entities to processes to glossary 5. **Document uncertainties** - Use `# TODO:` and `# QUESTION:` markers