orgmodel-update

name	orgmodel-update
description	Manage updates to organizational model documents and folder structures. Updates orgModel hierarchy including process documentation, domain models, collaboration diagrams, and test cases based on requirements processing results and domain analysis outputs.
license	MIT

OrgModel Update

Systematically manages updates to organizational model documents and folder structures based on analysis outputs from requirements processing and domain modeling.

Intent

Maintain the orgModel hierarchy with systematic updates to process documentation, domain models, collaboration diagrams, and test cases. Ensures organizational models remain current with evolving requirements while preserving existing content structure and maintaining cross-reference integrity.

Inputs

• Primary: projects/[project-name]/artifacts/Analysis/domain-concepts.json (from domain-extractconcepts skill)
• Secondary: projects/[project-name]/artifacts/Analysis/domain-alignment.json (from domain-alignentities skill)
• Tertiary: projects/[project-name]/artifacts/Analysis/collaboration-diagrams.json (from diagram-generatecollaboration skill)
• Context: projects/[project-name]/artifacts/Analysis/requirements.json (for traceability)
• Existing: orgModel/[NN] - [Process Name]/ (existing organizational model content)
• Diagram Updates: Class diagram updates triggered by domain alignment results

Outputs

Files Updated/Generated:

• orgModel/[NN] - [Process Name]/main.md - Updated process overview with new elements
• orgModel/[NN] - [Process Name]/domain-model.md - Updated domain model with aligned entities
• orgModel/[NN] - [Process Name]/process.md - Updated process flow documentation
• orgModel/[NN] - [Process Name]/collaboration.md - Updated collaboration diagrams
• orgModel/[NN] - [Process Name]/vocabulary.md - Updated terminology consistency mapping
• orgModel/[NN] - [Process Name]/test-case-list.md - Updated test case master list
• projects/[project-name]/artifacts/Analysis/orgmodel-update-summary.md - Change summary and validation report

Update Summary Structure (orgmodel-update-summary.md)

# OrgModel Update Summary

**Project**: [Project Name]  
**Generated**: [ISO8601 timestamp]  
**Process Model**: [NN] - [Process Name]  
**Source Analysis**: [source file references]

## Changes Applied

### Structure Updates
- [ ] Created new orgModel folder: `orgModel/[NN] - [Process Name]/`
- [ ] Updated existing structure with [N] new elements
- [ ] Preserved [N] existing elements

### Document Updates
- [ ] **main.md**: [summary of changes]
- [ ] **domain-model.md**: Added [N] entities, [N] concepts
- [ ] **process.md**: Updated with [N] new activities/flows  
- [ ] **collaboration.md**: Added [N] new interaction patterns
- [ ] **vocabulary.md**: Added [N] terms, aligned [N] existing terms
- [ ] **test-case-list.md**: Added [N] test cases, updated [N] existing

### Validation Results
- [ ] Cross-reference integrity maintained
- [ ] Terminology consistency verified
- [ ] Process flow completeness validated
- [ ] Test coverage assessment completed

## Next Steps
- Review updated orgModel for completeness
- Validate process flows with stakeholders
- Update dependent organizational models
- Schedule integration testing

Core Functions

1. OrgModel Structure Management

Create/Update Process Folder

orgModel/[NN] - [Process Name]/
├── main.md               # Process overview with navigation
├── domain-model.md       # Actors, systems, entities from domain analysis
├── process.md            # Process flows, activities, decision points
├── collaboration.md      # Entity interactions and sequence diagrams  
├── vocabulary.md         # Canonical terminology mapping
├── test-case-list.md     # Comprehensive test case registry
└── test-cases/           # Individual test case files (if testing required)
    └── tc-[proc-id]-[sequence].md

Numbering Convention: Use next available NN sequence number in orgModel folder structure

2. Content Generation Patterns

main.md Structure

<!-- Identifier: I-[NN] -->

# [NN] - [Process Name]

## Purpose
[Business purpose derived from requirements analysis]

## Process Flow  
See [process.md](process.md) for detailed activity diagram.

## Collaborations
See [collaboration.md](collaboration.md) for entity interactions.

## Domain Model
See [domain-model.md](domain-model.md) for actors and entities.

## Sub-Processes
[List nested processes identified from analysis]

## Test Coverage
See [test-case-list.md](test-case-list.md) for verification test cases.

## Related Changes
<!-- Traceability to source requirements and changes -->

domain-model.md Structure

<!-- Identifier: DM-[NN] -->

# Domain Model: [Process Name]

## Actors
[Human and system actors from domain analysis]

### [Actor Name]
- **Type**: Human/System/External
- **Responsibilities**: [key responsibilities]
- **Interactions**: [primary entity interactions]

## Key Entities
[Business entities from domain concepts extraction]

### [Entity Name] 
- **Definition**: [entity definition]
- **Attributes**: [key attributes]
- **Relationships**: [entity relationships]
- **Domain Area**: [functional area]

## Systems and Components
[Technical systems involved in process]

### [System Name]
- **Purpose**: [system role]
- **Interfaces**: [external connections]
- **Key Functions**: [primary capabilities]

process.md Structure

<!-- Identifier: P-[NN] -->

# Process: [Process Name]

## Overview
[Process purpose and scope]

## Process Flow

```mermaid
flowchart TD
    A[Start] --> B[Activity 1]
    B --> C{Decision Point}
    C -->|Yes| D[Activity 2]
    C -->|No| E[Activity 3]
    D --> F[End]
    E --> F

Activities

[Activity Name]

• Input: [required inputs]
• Process: [activity description]
• Output: [produced outputs]
• Responsible: [actor/role responsible]
• Validation: [quality checks]

Decision Points

[Critical decision points with criteria]

Exception Handling

[Error conditions and recovery procedures]

#### collaboration.md Structure
```markdown
<!-- Identifier: C-[NN] -->

# Collaboration: [Process Name]

## Entity Interactions

```mermaid
sequenceDiagram
    participant A as Actor
    participant S as System
    participant D as Data Store
    
    A->>S: Request
    S->>D: Query
    D-->>S: Response
    S-->>A: Result

Interaction Patterns

[Description of key interaction patterns]

Communication Channels

[How entities communicate]

Data Flow

[Information flow between entities]

#### vocabulary.md Structure
```markdown
<!-- Identifier: V-[NN] -->

# Vocabulary: [Process Name]

## Canonical Terms
[Standardized terminology for the process]

| Term | Definition | Aliases | Context |
|------|------------|---------|---------|
| [Term] | [Definition] | [Synonyms] | [Usage context] |

## Domain Alignment
[Mapping to enterprise domain models]

## Consistency Rules
[Guidelines for term usage across process]

test-case-list.md Structure

<!-- Identifier: TCL-[NN] -->

# Test Case List: [Process Name]

## Test Coverage Overview
[Summary of testing scope and approach]

## Test Cases

| TC ID | Test Category | Title | Priority | Source Requirement |
|-------|---------------|-------|----------|-------------------|
| tc-[NN]-001 | Functional | [Test title] | High | R-[ID] |

## Test Categories
- **Functional**: Core process functionality
- **Integration**: Cross-entity interactions  
- **Exception**: Error handling and recovery
- **Performance**: Process efficiency measures
- **Compliance**: Regulatory/standards adherence

## Validation Criteria
[Process success criteria for testing]

3. Content Update Logic

Preservation Strategy:

• Maintain existing content structure and identifiers
• Add new elements without disrupting existing cross-references
• Preserve manual customizations and annotations
• Update metadata and change tracking

Integration Patterns:

• Merge new domain entities with existing domain models
• Append new process activities to existing flows
• Integrate new collaboration patterns with existing interactions
• Add new terminology while maintaining consistency
• Extend test coverage without duplicating existing cases

Domain Model Updates with Class Diagrams

When updating domain-model.md, this skill now integrates with diagram generation:

Class Diagram Integration Process

1. Extract existing entities from textual domain model descriptions
2. Apply alignment results from domain-alignentities skill
3. Generate/update class diagram reflecting aligned domain structure
4. Embed diagram in domain-model.md following organizational patterns
5. Sync diagram with textual descriptions to ensure consistency

domain-model.md Enhanced Structure

<!-- Identifier: D-[NN] -->

# [Process Name] Domain Model

## Domain Class Diagram

```mermaid
classDiagram
    class Entity:::category {
        +attribute: Type
        +operation()
    }
    
    Entity --> RelatedEntity
    
    %% Styling Definitions
    classDef actor fill:#e1f5fe
    classDef entity fill:#f3e5f5
    classDef enum fill:#fff3e0
    classDef ai fill:#e8f5e8

Actors

[Textual descriptions of actors shown in diagram]

Core Entities

[Textual descriptions of entities with attributes and operations]

Key Relationships

[Textual descriptions of relationships shown in diagram]

#### Diagram-Text Synchronization
- **Entity alignment**: Ensure diagram entities match textual descriptions
- **Attribute consistency**: Sync diagram attributes with detailed attribute lists  
- **Operation alignment**: Match diagram operations with described behaviors
- **Relationship validation**: Verify diagram associations match textual relationships
- **Styling consistency**: Apply organizational diagram styling standards with proper classDef definitions
- **Style preservation**: Maintain standard organizational colors (actor: #e1f5fe, entity: #f3e5f5, enum: #fff3e0, ai: #e8f5e8)

### 4. Validation and Integrity Checks

**Integration with Diagram Generation**:
- **Trigger diagram updates** when domain alignment results indicate changes
- **Coordinate with diagram-generatecollaboration** skill for class diagram generation
- **Maintain diagram version consistency** across organizational models
- **Preserve custom diagram styling** and layout preferences
- **Ensure styling definitions included** - All class diagrams must include classDef statements for proper rendering
- **Validate diagram syntax** - Check that both inline styling (:::category) and style definitions (classDef) are present

**Cross-Reference Validation**:
- Verify all internal links to process documents remain valid
- Ensure terminology consistency across all orgModel files
- Validate entity references between domain model and collaborations
- Check test case traceability to source requirements

**Structure Integrity**:
- Confirm file naming conventions compliance
- Validate Mermaid diagram syntax in process.md and collaboration.md
- Ensure required sections present in all core files
- Verify identifier uniqueness across orgModel structure

**Content Consistency**:
- Align terminology with vocabulary.md across all files
- Ensure actor consistency between domain-model.md and collaboration.md
- Validate process flow completeness and logical consistency
- Check test case coverage against identified process activities

## Usage Guidelines

### Typical Workflow
1. **Analyze Input**: Process domain concepts, alignment results, and collaboration diagrams
2. **Identify Target**: Determine orgModel process (existing or new) for updates
3. **Structure Update**: Create/modify orgModel folder structure as needed
4. **Content Integration**: Update each core file with new elements, preserving existing content
5. **Validation**: Run integrity checks and cross-reference validation
6. **Summary Generation**: Document all changes and validation results

### Integration Points
- **Domain Analysis**: Incorporates entities and concepts from domain extraction
- **Process Modeling**: Integrates with collaboration diagram generation
- **Requirements Traceability**: Maintains links to source requirements
- **Change Management**: Documents updates for organizational tracking
- **Testing Integration**: Provides test case foundation for validation activities

### Quality Assurance
- Apply organizational naming conventions consistently
- Ensure Mermaid diagram syntax validity
- Maintain document template compliance
- Validate cross-reference integrity
- Confirm terminology alignment with enterprise standards

## Configuration Options

### Process Identification
- **Auto-numbering**: Automatically assign next available orgModel sequence number
- **Manual numbering**: Use specified process number for updates
- **Name mapping**: Map requirements/domain areas to existing process models

### Update Mode
- **Incremental**: Add new elements to existing orgModel content
- **Refresh**: Regenerate orgModel content while preserving customizations
- **Merge**: Combine multiple analysis sources into single orgModel update

### Validation Level
- **Basic**: File structure and syntax validation
- **Standard**: Cross-reference and consistency checking  
- **Comprehensive**: Full integrity validation with dependency analysis

---

**Dependencies**: domain-extractconcepts, domain-alignentities, diagram-generatecollaboration
**Integration**: GitHub Copilot, VS Code environment, EDPS skill framework, Mermaid class diagram generation
**Maintenance**: Update templates based on organizational model evolution
**Diagram Support**: Automatic class diagram generation and synchronization with textual domain models