@codemcp/workflows-core 3.1.21 → 3.2.0

package/resources/workflows/business-analysis.yaml

@@ -0,0 +1,671 @@
+# yaml-language-server: $schema=../state-machine-schema.json
+---
+name: 'business-analysis'
+description: 'Business Capability Modeling workflow that analyzes systems from a pure business perspective. Creates hierarchical business capability maps, service catalogs, and process documentation using industry-standard Business Capability Modeling methodology.'
+initial_state: 'document_discovery'
+
+# Enhanced metadata for better discoverability
+metadata:
+  domain: 'architecture'
+  complexity: 'medium'
+  bestFor:
+    - 'Business capability modeling'
+    - 'Business architecture analysis'
+    - 'Business service cataloging'
+    - 'Business process documentation'
+  useCases:
+    - 'Create business capability maps from system documentation'
+    - 'Document business services and processes'
+    - 'Analyze organizational business functions'
+  examples:
+    - 'Model business capabilities for legacy system understanding'
+    - 'Create business service catalog for domain architects'
+    - 'Document business processes and organizational roles'
+
+# States with default instructions and transitions
+states:
+  document_discovery:
+    description: 'Gather business documents and create standardized Business Capability Modeling structure'
+    default_instructions: >
+      You are in the document discovery phase. Gather documents and create standardized Business Capability Modeling structure.
+
+      **Step 1: Interactive Document Gathering**
+      Ask user to identify and provide available documents:
+      - Business process documentation
+      - Organizational charts
+      - System documentation
+      - Existing c4-analysis results
+      - Business requirements documents
+
+      IMPORTANT: In this phase, do not read the documents yet!
+
+      **Step 2: Create Document Processing Tasks**
+      For each gathered document, add task to plan file:
+      "- [ ] Summarize [document-name] using structured chapter-by-chapter approach"
+
+      Update plan file with discovery progress and processing tasks.
+    transitions:
+      - trigger: 'discovery_complete'
+        to: 'documents_consolidation'
+        additional_instructions: >
+          Document discovery is complete! ✅ Now transition to documents consolidation phase.
+
+          Begin systematic document processing using structured summarization technique.
+          Mark completed discovery tasks in plan file.
+        transition_reason: 'Documents gathered and Business Capability Modeling structure created, ready for consolidation'
+
+  documents_consolidation:
+    description: 'Process and consolidate gathered documents using structured summarization'
+    default_instructions: >
+      You are in the documents consolidation phase. Process each document systematically using basic structured summarization.
+
+      **Step 1: Apply Structured Summarization Technique**
+      For each document, use this approach:
+
+      1. Read document chapter by chapter
+      2. Maintain original hierarchical structure
+      3. Condense content while preserving key information
+      4. Create [document-name]-processed.md file
+      5. Mark task complete in plan file
+
+      **Summarization Guidelines:**
+      - Create structured summary based exclusively on source document information
+      - Identify chapters and hierarchy levels systematically
+      - Summarize level-by-level into [document-name]-processed.md
+      - Write chapter summaries in natural language (no bullet points)
+      - Include information about potential capabilities, services, processes, or actors
+      - Maintain folder structure if documents have associated folders
+
+      **Step 2: Create Bibliography**
+      Create BIBLIOGRAPHY.md with:
+      - "sources" section listing all processed documents
+      - "terms" section with important business terms and their source references
+
+      IMPORTANT: This phase focuses only on basic document processing. Business analysis happens in the next phase.
+    transitions:
+      - trigger: 'consolidation_complete'
+        to: 'business_content_analysis'
+        additional_instructions: >
+          Documents consolidation is complete! ✅ Now transition to business content analysis.
+
+          Begin identifying business-relevant chapters for detailed analysis.
+          Mark completed consolidation tasks in plan file.
+        transition_reason: 'Basic document processing complete, ready for business content analysis'
+
+  business_content_analysis:
+    description: 'Identify and analyze business-relevant content from processed documents'
+    default_instructions: >
+      You are in the business content analysis phase. Focus on identifying and analyzing business-relevant content.
+
+      **Step 1: Review Processed Documents**
+      Review all [document-name]-processed.md files from consolidation phase.
+      Identify chapters that contain business-relevant content:
+      - Business processes and workflows
+      - Organizational roles and responsibilities
+      - Business capabilities and functions
+      - Services and customer interactions
+      - Business rules and policies
+
+      **Step 2: Create Business Analysis Tasks**
+      For each business-relevant chapter identified, add a task to the plan file:
+      "- [ ] Create detailed business analysis of [document-name] Chapter [X]: [chapter-title]"
+
+      IMPORTANT: You MUST add these tasks to the plan file before proceeding.
+
+      **Step 3: Execute Business Analysis Tasks**
+      For each business analysis task:
+      1. Read the specific chapter in detail
+      2. Extract business information focusing on:
+         - What business capabilities are mentioned
+         - What services or processes are described
+         - Who (roles/actors) performs the work
+         - Why (business value/purpose) it exists
+      3. Create detailed business summary emphasizing WHAT, WHY, WHO (not HOW)
+      4. Mark task complete in plan file
+
+      **Step 4: Update Bibliography**
+      Update BIBLIOGRAPHY.md with business terms found during detailed analysis:
+      - check whether the "sources" section already contains an entry it. If not: create one (max 5 letters in brackets).
+      - In the "terms" section, check whether there is an entry for it - If not, create an entry for It
+      - add a reference to the source + chapter
+
+      --- sample 1 ---
+
+      Document "operations manual" reads about "payment processing" in Chapter 5.2
+
+      => in BIBLIOGRAPHY.md
+
+      # Sources
+
+      - Operations Manual [OPMAN]
+
+      # Terms
+
+      - payment processing
+        - OPMAN, 5.2
+
+      --- end of sample 1 ---
+
+      --- sample 2 ---
+
+      Document "requirements.md" reads about "payment processing" in Chapter 1.2.1
+
+      => in BIBLIOGRAPHY.md
+
+      # Sources
+
+      - Requirements [REQ]
+
+      # Terms
+
+      - payment processing
+        - REQ, 1.2.1
+
+      --- end of sample 2 ---
+
+      Process business analysis tasks systematically, one at a time.
+    transitions:
+      - trigger: 'business_analysis_complete'
+        to: 'capability_identification'
+        additional_instructions: >
+          Business content analysis is complete! ✅ Now transition to capability identification.
+
+          Create BUSINESS_ANALYSIS.md with the following template content:
+          ```markdown
+          # Business Analysis Report
+
+          *This report documents business capabilities using Business Capability Modeling methodology. It provides a hierarchical view of what the business does, how it delivers value, and who performs the work.*
+
+          ## Methodology
+          This analysis uses **Business Capability Modeling**, an industry-standard approach for understanding business architecture:
+
+          - **Business Domains**: High-level areas of business activity
+          - **Business Capabilities**: What the business does (stable, outcome-focused)
+          - **Business Services**: How capabilities are delivered to consumers
+          - **Business Processes**: Step-by-step activities that deliver services
+          - **Business Actors**: Roles and organizational units that perform the work
+
+          **Hierarchy**: Domain → Capability → Sub-Capability → Service → Process → Actor
+
+          ## Executive Summary
+          <!-- High-level business capability overview -->
+
+          ## Business Domains Identified
+          <!-- Main business domains discovered -->
+
+          ## Key Business Capabilities
+          <!-- Primary capabilities mapped hierarchically -->
+
+          ## Business Services Catalog
+          <!-- Services that deliver capabilities -->
+
+          ## Business Architecture Insights
+          <!-- Important findings and patterns -->
+
+          ## Recommendations
+          <!-- Business capability recommendations -->
+          ```
+
+          Create business-processes-detailed.md with template:
+          ```markdown
+          # Business Processes Detailed
+
+          ## Overview
+          This document details business processes for each capability.
+
+          ## Process Overview by Capability
+          <!-- Process summaries for each capability -->
+
+          ## Process Flow Diagrams
+          <!-- Detailed process flows -->
+
+          ## Process Actors and Responsibilities
+          <!-- Key roles in each process -->
+          ```
+
+          Create business-functions-mapping.md with template:
+          ```markdown
+          # Business Functions Mapping
+
+          ## Overview
+          This document maps organizational functions to business capabilities.
+
+          ## Organizational Structure
+          <!-- High-level org structure -->
+
+          ## Function-Capability Mappings
+          <!-- Which functions support which capabilities -->
+
+          ## Roles and Responsibilities
+          <!-- Key roles and their responsibilities -->
+          ```
+
+          Create technical-business-mapping.md with template:
+          ```markdown
+          # Technical-Business Mapping
+
+          ## Overview
+          This document maps technical components to business capabilities.
+
+          ## Technical Architecture Overview
+          <!-- High-level technical architecture -->
+
+          ## Component-Capability Mappings
+          <!-- Which technical components support which capabilities -->
+
+          ## Business Value Assessments
+          <!-- Business value of each technical component -->
+          ```
+
+          Create Standardized Business Capability Modeling folder Structure
+            - business-analysis/business-domains/ (folder for details)
+            - business-analysis/business-capabilities/ (folder for details)
+            - business-analysis/business-processes/ (folder for details)
+            - business-analysis/business-actors/ (folder for details)
+
+          Begin analyzing processed documents to identify business capabilities and domains.
+          Mark completed business analysis tasks in plan file.
+        transition_reason: 'Business content analysis complete, ready for capability identification'
+
+  capability_identification:
+    description: 'Identify business capabilities from processed documents'
+    default_instructions: >
+      You are in the capability identification phase. Analyze processed documents to identify business capabilities.
+
+      IMPORTANT: ALWAYS reference the existing documents!
+
+      **Step 1: Analyze Processed Documents**
+      Review all [document-name]-processed.md files from consolidation phase.
+      Look for:
+      - Business functions mentioned
+      - Activities and processes described
+      - Services or offerings referenced
+      - Organizational responsibilities
+      - System functionalities with business purpose
+
+      **Step 2: Extract Potential Capabilities**
+      From document analysis, create initial list of business capabilities.
+      Group similar activities and functions together.
+      Use Business Capability Modeling naming: [Verb] + [Business Object] (e.g., "Manage Customers", "Process Orders")
+
+      **Step 3: Identify Business Domains**
+      Group capabilities into logical business domains:
+      - Customer-related capabilities → Customer Management
+      - Order-related capabilities → Order Management
+      - Financial capabilities → Financial Management
+      - etc.
+
+      **Step 4: Present Findings to User**
+      Show user the identified capabilities and domains:
+      "Based on the documents, I identified these business domains and capabilities:
+      [Present structured list]
+
+      Do these align with your understanding?
+      Are there any capabilities missing or incorrectly categorized?"
+
+      **Step 5: Refine with User Input**
+      Adjust the capability model based on user feedback.
+      Document final capability list in business-capabilities.md.
+
+    transitions:
+      - trigger: 'capabilities_identified'
+        to: 'capability_decomposition'
+        additional_instructions: >
+          Capability identification is complete! ✅ Now transition to capability decomposition.
+
+          For each identified capability, add decomposition tasks to plan file:
+          "- [ ] Decompose [capability-name] into sub-capabilities using document analysis"
+
+          Begin systematic decomposition of capabilities one at a time.
+          Mark completed identification tasks in plan file.
+        transition_reason: 'Business capabilities identified, ready for detailed decomposition'
+
+  capability_decomposition:
+    description: 'Break down business capabilities into detailed sub-capabilities using document analysis'
+    default_instructions: >
+      You are in the capability decomposition phase. Analyze documents to identify sub-capabilities, then validate with user.
+
+      IMPORTANT: ALWAYS reference the existing documents!
+
+      **Step 1: Analyze Documents for Sub-capabilities**
+      Review processed documents for the next unprocessed capability:
+      - Look for detailed activities mentioned within this capability
+      - Identify specific processes or functions described
+      - Find decision points and workflow steps
+      - Note different outcomes or deliverables mentioned
+
+      **Step 2: Extract Potential Sub-capabilities**
+      From document analysis, create initial list of sub-capabilities.
+      Use Business Capability Modeling naming: [Verb] + [Business Object]
+      Example: For "Customer Management" → "Verify Customer Identity", "Setup Customer Account", "Maintain Customer Data"
+
+      **Step 3: Present Findings to User**
+      Show user the identified sub-capabilities:
+      "Based on the documents, I identified these sub-capabilities for [capability]:
+      [Present structured list]
+
+      Do these sub-capabilities accurately reflect [capability]?
+      Are any activities missing or incorrectly categorized?"
+
+      **Step 4: Refine with User Input**
+      Adjust the sub-capability model based on user feedback.
+      Document refined decomposition in business-capabilities/ detail folder.
+      Mark capability as complete and ask: "Ready for the next capability?"
+
+    transitions:
+      - trigger: 'decomposition_complete'
+        to: 'actor_analysis'
+        additional_instructions: >
+          Capability decomposition is complete! ✅ Now transition to actor analysis.
+
+          Create business-actors.md with template:
+          ```markdown
+          # Business Actors
+
+          ## Overview
+          This document maps business actors (roles and organizational units) to capabilities using Business Capability Modeling methodology.
+
+          ## Actor-Capability Mappings
+          <!-- For each capability, document:
+          - Primary Owner: Who is accountable for capability outcomes
+          - Performing Roles: Which roles actually execute the capability
+          - Supporting Units: Which organizational units support the capability
+          - Decision Authority: Who has authority to change/approve within this capability -->
+
+          ## Role Definitions
+          <!-- Detailed definitions of key business roles -->
+
+          ## Organizational Units
+          <!-- Key organizational units and their responsibilities -->
+          ```
+
+          For each capability, add actor analysis tasks to plan file:
+          "- [ ] Analyze business actors for [capability-name] using document analysis"
+
+          Begin systematic actor analysis one capability at a time.
+          Mark completed decomposition tasks in plan file.
+        transition_reason: 'Capability decomposition complete, ready for actor analysis'
+
+  actor_analysis:
+    description: 'Map business actors (roles and organizational units) to capabilities using systematic task-based approach'
+    default_instructions: >
+      You are in the actor analysis phase. Identify WHO performs each capability using Business Capability Modeling approach.
+
+      **Step 1: Select Next Capability for Actor Analysis**
+      From plan file, select the next capability to analyze for business actors.
+
+      **Step 2: Analyze Documents for Business Actors**
+      Review processed documents to identify:
+      - **Business Roles**: Specific job roles (Customer Service Rep, Account Manager, etc.)
+      - **Organizational Units**: Teams/departments (Sales Team, Finance Department, etc.)
+      - **Decision-making Authority**: Who makes decisions for this capability
+      - **Accountability**: Who is responsible for capability outcomes
+
+      **Step 3: Map Actors to Capabilities**
+      For the selected capability, identify:
+      - **Primary Owner**: Who is accountable for capability outcomes
+      - **Performing Roles**: Which roles actually execute the capability
+      - **Supporting Units**: Which organizational units support the capability
+      - **Decision Authority**: Who has authority to change/approve within this capability
+
+      **Step 4: Create Actor Analysis Document**
+      Document the actor mappings in business-actors.md:
+      - **Primary Owner**: Who is accountable for capability outcomes
+      - **Performing Roles**: Which roles actually execute the capability
+      - **Supporting Units**: Which organizational units support the capability
+      - **Decision Authority**: Who has authority to change/approve within this capability
+
+      Then present to user for validation:
+      "I documented the business actors for [capability]. Please review the actor mappings - do they accurately reflect WHO performs this capability?"
+
+      **Step 5: Refine and Document**
+      Update business-actors.md with capability-actor mappings.
+      Mark task complete in plan file.
+
+      Focus on capability ownership and role accountability, not just organizational structure.
+
+      Process one capability's functions at a time.
+    transitions:
+      - trigger: 'actor_analysis_complete'
+        to: 'process_analysis'
+        additional_instructions: >
+          Actor analysis is complete! ✅ Now transition to process analysis.
+
+          Create business-processes.md with template:
+          ```markdown
+          # Business Processes
+
+          ## Overview
+          This document details business processes that deliver capabilities.
+
+          ## Process Overview by Capability
+          <!-- Process summaries for each capability -->
+
+          ## Process Flow Diagrams
+          <!-- Detailed process flows and decision points -->
+
+          ## Process-Actor Relationships
+          <!-- How processes relate to the actors identified -->
+          ```
+
+          For each capability, add process analysis tasks to plan file:
+          "- [ ] Analyze business processes for [capability-name] using document analysis and actor context"
+
+          Begin systematic process analysis one capability at a time.
+          Mark completed actor analysis tasks in plan file.
+        transition_reason: 'Actor analysis complete, ready for process analysis'
+
+  process_analysis:
+    description: 'Analyze business processes using systematic task-based approach'
+    default_instructions: >
+      You are in the process analysis phase. Create process analysis tasks for systematic processing.
+
+      **Step 1: Select Next Process Analysis Task**
+      From plan file process analysis tasks, select the next capability to process.
+
+      **Step 2: Analyze Documents for Process Information**
+      Review processed documents for process information:
+      - Look for process steps, workflows, decision points
+      - Identify process actors, inputs, outputs
+      - Note process triggers and outcomes
+      - Find process rules and constraints
+
+      **Step 3: Extract Processes**
+      Create process flows from document analysis.
+      Document process characteristics:
+      - Process name and purpose
+      - Process steps and sequence
+      - Decision points and branches
+      - Process actors and responsibilities
+      - Inputs, outputs, and deliverables
+
+      **Step 4: Present to User**
+      Show identified processes and ask for validation:
+      "Based on documents, I identified these processes for [capability]:
+      [Present process flows]
+
+      Do these processes accurately reflect how [capability] works?
+      Are any process steps missing or incorrectly sequenced?"
+
+      **Step 5: Refine and Document**
+      Update business-processes-detailed.md and detail folder.
+      Mark task complete in plan file.
+
+      Process one capability's processes at a time.
+    transitions:
+      - trigger: 'process_analysis_complete'
+        to: 'consistency'
+        additional_instructions: >
+          Process analysis is complete! ✅ Now transition to consistency phase.
+
+          Present the Business Capability Consistency Framework to user:
+          "I'll now validate consistency across all analysis documents using this framework:
+
+          **Business Capability Consistency Framework:**
+          - **Capability-Process Alignment**: Do processes actually deliver the stated capabilities?
+          - **Actor-Capability Ownership**: Are actors properly assigned to capability outcomes?
+          - **Process-Actor Mapping**: Do processes reference the correct performing actors?
+          - **Cross-Document Coherence**: Same entities described consistently across documents?
+          - **Completeness Validation**: All expected sections present and properly linked?
+
+          This ensures our business capability model is internally consistent before final summary.
+          Ready to proceed with consistency validation?"
+
+          Begin systematic consistency validation across all analysis documents.
+          Mark completed process analysis tasks in plan file.
+        transition_reason: 'Process analysis complete, ready for consistency validation'
+
+  consistency:
+    description: 'Validate consistency across all business capability analysis documents'
+    default_instructions: >
+      You are in the consistency phase. Validate consistency across all analysis documents using the Business Capability Consistency Framework.
+
+      **Step 1: Re-discover Analysis Documents**
+      Scan workspace for all created analysis documents:
+      - business-domains.md and detail folders
+      - business-capabilities.md and detail folders  
+      - business-processes.md and detail folders
+      - business-actors.md and detail folders
+      - BUSINESS_ANALYSIS.md
+      - Any other analysis artifacts created
+
+      **Step 2: Apply Consistency Framework**
+      For each consistency check:
+
+      **Capability-Process Alignment Check:**
+      - Do documented processes actually deliver the stated capabilities?
+      - Are there capabilities without supporting processes?
+      - Are there processes that don't map to any capability?
+
+      **Actor-Capability Ownership Check:**
+      - Is each capability assigned a clear primary owner (actor)?
+      - Are performing roles properly mapped to capabilities?
+      - Do actors have decision authority for their assigned capabilities?
+
+      **Process-Actor Mapping Check:**
+      - Do processes reference the correct performing actors?
+      - Are actor responsibilities aligned with process steps?
+      - Is there clear accountability in each process?
+
+      **Cross-Document Coherence Check:**
+      - Are capabilities named consistently across documents?
+      - Do actor definitions match across process and capability docs?
+      - Are business terms used consistently throughout?
+
+      **Completeness Validation:**
+      - Are all expected document sections present?
+      - Do internal links work correctly?
+      - Are references to other documents accurate?
+
+      **Step 3: Document Issues and Fixes**
+      Create CONSISTENCY_REPORT.md documenting:
+      - Issues found during validation
+      - Fixes applied to resolve inconsistencies
+      - Remaining gaps or recommendations
+
+      **Step 4: Present Findings to User**
+      Show consistency validation results and ask for confirmation:
+      "Consistency validation complete. Found [X] issues, resolved [Y]. 
+      Key findings: [summary of major consistency improvements]
+
+      Are you satisfied with the consistency of the business capability model?"
+
+      Focus on ensuring the business capability model is internally coherent before final summary.
+    transitions:
+      - trigger: 'consistency_complete'
+        to: 'summary'
+        additional_instructions: >
+          Consistency validation is complete! ✅ Now transition to summary phase.
+
+          Ask user about illustration format preference:
+          "How would you like diagrams and illustrations formatted in the final summary?
+          - ASCII diagrams (text-based, simple)
+          - Mermaid diagrams (code-based, rich formatting)  
+          - PlantUML diagrams (UML standard, detailed)
+          - All three formats (comprehensive)"
+
+          Begin creating consolidated summaries and illustrations.
+          Mark completed consistency tasks in plan file.
+        transition_reason: 'Consistency validation complete, ready for final summary creation'
+
+  summary:
+    description: 'Create consolidated summaries and illustrations for business capability analysis'
+    default_instructions: >
+      You are in the summary phase. Create consolidated overviews and illustrations using user's preferred formats.
+
+      **Step 1: Create Consolidated Overviews**
+      Build comprehensive summary documents:
+      - **Executive Summary**: High-level business capability overview for leadership
+      - **Capability Map**: Hierarchical view of all business capabilities
+      - **Actor-Capability Matrix**: Who owns/performs each capability
+      - **Process Overview**: Key processes supporting capabilities
+      - **Navigation Guide**: How to use all analysis documents
+
+      **Step 2: Generate Illustrations**
+      Using user's chosen format(s) (ASCII/Mermaid/PlantUML):
+      - Business capability hierarchy diagrams
+      - Process flow diagrams
+      - Actor-capability relationship maps
+      - Cross-functional process flows
+      - Organizational responsibility charts
+
+      **Step 3: Fix Links and References**
+      - Standardize internal document links
+      - Create cross-references between related content
+      - Build table of contents for navigation
+      - Ensure all references are accurate and working
+
+      **Step 4: Update BUSINESS_ANALYSIS.md**
+      Finalize the main analysis document with:
+      - Complete executive summary
+      - Key findings and insights
+      - Business architecture recommendations
+      - Links to all detailed analysis documents
+      - Methodology explanation and validation results
+
+      **Step 5: Present Final Deliverables**
+      Show completed analysis to user:
+      "Business Capability Analysis complete! Final deliverables:
+      [Present overview of all documents, diagrams, and summaries]
+
+      This provides comprehensive business architecture understanding for domain architects.
+      Are you satisfied with the final analysis deliverables?"
+
+      Focus on creating business-friendly, navigable documentation that serves domain architects.
+    transitions:
+      - trigger: 'summary_complete'
+        to: 'analysis_complete'
+        additional_instructions: >
+          Summary creation is complete! ✅
+
+          Final Business Capability Analysis deliverables ready:
+          - Consolidated executive summaries
+          - Business capability maps and diagrams
+          - Actor-capability matrices
+          - Process flow documentation
+          - Navigation guides and cross-references
+
+          The analysis provides complete business architecture understanding using Business Capability Modeling methodology.
+          Mark completed summary tasks in plan file.
+        transition_reason: 'Summary creation complete, analysis finished'
+
+  analysis_complete:
+    description: 'Business analysis complete'
+    default_instructions: >
+      Business analysis is complete! The system has been thoroughly analyzed using Business Capability Modeling methodology.
+
+      Final deliverables:
+      - Comprehensive business architecture documentation (Business Capability Modeling-based)
+      - BUSINESS_ANALYSIS.md with complete analysis findings
+      - Business capability maps and process flows
+      - Technical-business alignment documentation
+      - Business-friendly documentation for domain architects
+
+      The analysis provides a solid foundation for business architecture decisions and technical-business alignment.
+    transitions:
+      - trigger: 'analysis_complete'
+        to: 'analysis_complete'
+        instructions: >
+          Analysis is complete! The business architecture is now well-documented and understood.
+          Use the comprehensive documentation for business architecture decisions and planning.
+        transition_reason: 'Analysis complete, ready for business architecture work'