requirements-merge

name	requirements-merge
description	Combines multiple requirement sources into a single coherent specification, handling conflicts and redundancies while maintaining source traceability and supporting stakeholder review workflows.
license	MIT

Requirements Merge

Intelligently merges requirements from multiple sources and formats into a unified, coherent specification while identifying conflicts, eliminating redundancies, preserving important variations, and maintaining complete source traceability throughout stakeholder review processes.

Core Function

Input: Multiple requirements documents + project_id + merge_strategy + conflict_resolution_rules Primary Output: Markdown unified requirements specification (for stakeholder review and downstream skills) Secondary Output: JSON format with detailed merge analysis and traceability (for machine processing and audit trails) Output Destination:

• Markdown: outputs/projects/{project_id}/Analysis/unified-requirements.md (primary for downstream)
• JSON: outputs/projects/{project_id}/Analysis/merge-analysis.json (machine processing)
• Conflicts Log: outputs/projects/{project_id}/Analysis/merge-conflicts.md (stakeholder review) Directory Structure: Auto-created project folders with Analysis subfolder containing unified requirements, merge analysis, conflict resolution logs, and stakeholder approval tracking

Usage

GitHub Copilot Integration (Recommended):

Use this skill directly in Copilot by providing multiple requirements documents and merge strategy.
Copilot will automatically merge requirements, identify conflicts, and produce a unified specification.

Example prompt:
"Use requirements-merge skill to merge these three requirements documents: [doc1.md], [doc2.pdf], [doc3.docx]. Apply conservative merge strategy with manual conflict resolution for high-impact conflicts."

Traditional Script Approach:

from process_merge import RequirementsMerger

merger = RequirementsMerger()
result = merger.merge_requirements([
    "requirements-v1.md", 
    "stakeholder-feedback.docx", 
    "technical-constraints.pdf"
], "PROJECT-001", merge_strategy="comprehensive")
# Creates: 
#   outputs/projects/PROJECT-001/unified-requirements.md (primary)
#   outputs/projects/PROJECT-001/merge-analysis.json (secondary)
#   outputs/projects/PROJECT-001/merge-conflicts.md (stakeholder review)

Command Line:

python process_merge.py PROJECT-001 --strategy comprehensive requirements-v1.md stakeholder-feedback.docx technical-constraints.pdf
# Saves to: outputs/projects/PROJECT-001/
#   📄 unified-requirements.md (Markdown - for downstream skills)
#   📋 merge-analysis.json (JSON - for machine processing)
#   ⚠️ merge-conflicts.md (Conflicts - for stakeholder review)

Output Schema

Primary Format (Markdown) - Unified Requirements Specification:

# Unified Requirements Specification

**Project**: PROJECT-001
**Merge Date**: 2026-02-15T10:30:00Z
**Sources Merged**: 3 documents (requirements-v1.md, stakeholder-feedback.docx, technical-constraints.pdf)
**Total Requirements**: 47 (15 core, 20 merged, 12 enhanced)
**Conflicts Resolved**: 8 (3 automatic, 5 stakeholder-reviewed)
**Merge Strategy**: Comprehensive with stakeholder validation

## Executive Summary

**Merge Outcome**: Successfully unified 3 requirement sources into coherent specification
**Quality Metrics**: 96% requirement coverage, 100% traceability maintained
**Stakeholder Impact**: 5 conflicts requiring stakeholder review and approval
**Next Steps**: Stakeholder review of conflict resolutions, final approval workflow

## Requirements by Category

### Core Requirements (Consensus Across Sources)

#### R-001: User Authentication
**Unified Requirement**: System shall authenticate users using multi-factor authentication within 3 seconds
**Source Traceability**: 
- requirements-v1.md (R-003): "System shall authenticate users within 3 seconds"
- stakeholder-feedback.docx (SF-012): "Must support multi-factor authentication"
- technical-constraints.pdf (TC-007): "Authentication response time ≤ 3 seconds"
**Merge Method**: Consensus enhancement
**Confidence Level**: High (100% source agreement)

#### R-002: Data Storage Compliance
**Unified Requirement**: All user data shall be stored in compliance with GDPR, CCPA, and SOX regulations with end-to-end encryption
**Source Traceability**:
- requirements-v1.md (R-015): "Data storage must comply with GDPR"
- stakeholder-feedback.docx (SF-008): "Need CCPA and SOX compliance"
- technical-constraints.pdf (TC-003): "Implement end-to-end encryption for all data"
**Merge Method**: Regulatory aggregation
: High (regulatory requirements)




: API response times shall not exceed 200ms for 95% of requests, with maximum timeout of 500ms
:
 requirements-v1.md (R-007): "API response < 200ms average"
 stakeholder-feedback.docx (SF-015): "Response time must be < 100ms"
 technical-constraints.pdf (TC-011): "Maximum response time 500ms"
: Stakeholder priority + technical feasibility analysis
: Approved 200ms/95th percentile standard (Date: 2026-02-14)
: High (stakeholder validated)


: Support iOS 14+, Android 10+, with progressive web app fallback for older versions
:
 requirements-v1.md (R-022): "Support iOS and Android latest 2 versions"
 stakeholder-feedback.docx (SF-023): "Must support iOS 12+ for legacy devices"
 technical-constraints.pdf (TC-015): "Progressive web app for cross-platform compatibility"
: Comprehensive coverage strategy
: Medium (implementation complexity uncertainty)




: Interface shall comply with WCAG 2.1 AA standards including screen reader support
: stakeholder-feedback.docx (SF-031): "Need accessibility for compliance"
: Legal compliance requirement, no conflicts with existing specifications
: High (regulatory requirement)






: OAuth2 vs SAML vs proprietary authentication
: 
 requirements-v1.md: OAuth2 preference
 stakeholder-feedback.docx: SAML required for enterprise
 technical-constraints.pdf: Proprietary solution suggested
: Multi-protocol support (OAuth2 primary, SAML enterprise, API fallback)
: Pending (escalated to architecture review board)
: Medium complexity increase, high flexibility gain


: 7 years vs 5 years vs indefinite retention
:
 requirements-v1.md: 7 years for audit compliance
 stakeholder-feedback.docx: 5 years sufficient for business needs
 technical-constraints.pdf: Storage costs favor shorter retention
: 7 years active, 5 years archived, purge after 7 years
: Approved by legal and finance teams (2026-02-13)
: Low complexity, balanced cost and compliance




: Cloud-native vs hybrid vs on-premises deployment
: All three sources present different preferences
: High (affects entire technical architecture)
: Executive decision required
: 2026-02-20
: Cloud-native development with hybrid deployment option preserved





: 12 duplicate performance specifications consolidated into 4 unified requirements
: 8 overlapping security requirements merged into 3 comprehensive specifications
: 6 similar API integration requests consolidated into 2 detailed specifications



: Maintained separate GDPR, CCPA, and SOX requirements due to different implementation approaches
: Preserved desktop, mobile, and tablet-specific UI requirements due to different interaction patterns
: Maintained REST, GraphQL, and WebSocket requirements for different use case optimizations




 : 73 (across 3 sources)
 : 47 (35% consolidation efficiency)
 : 8 (11% conflict rate)
 : 3 conflicts (37.5%)
 : 5 conflicts (62.5%)
 : 100% (all requirements traced to sources)


 : ✅ All source requirements addressed
 : ✅ No internal contradictions in unified specification
 : ✅ Complete source-to-unified mapping maintained
 : 🟨 85% approved, 15% pending review




 : Automated analysis identifies conflicting requirements
 : Business and technical impact evaluation for each conflict
 : Relevant stakeholders notified of conflicts requiring review
 : Facilitated stakeholder sessions for conflict resolution
 : Formal recording of stakeholder decisions and rationale
 : Status tracking for all review and approval activities


 : ✅ Approved unified technical requirements
 : 🟨 Approved core business requirements, reviewing performance conflicts
 : ✅ Approved all regulatory and compliance requirements
 : 🟨 Approved project scope, reviewing timeline impact of conflicts


  for authentication protocol decision (CR-001)
  with executive stakeholders (CR-003)
  based on conflict resolution outcomes
  after all conflicts resolved



| Unified ID | Original Sources | Merge Type | Stakeholder Status |
|------------|------------------|------------|-------------------|
| R-001 | requirements-v1.md:R-003, stakeholder-feedback.docx:SF-012 | Enhancement | Approved |
| R-002 | requirements-v1.md:R-015, technical-constraints.pdf:TC-003 | Aggregation | Approved |
| R-003 | requirements-v1.md:R-007, stakeholder-feedback.docx:SF-015 | Conflict Resolution | Approved |
| R-004 | All 3 sources (variations preserved) | Comprehensive | Pending |
| R-005 | stakeholder-feedback.docx:SF-031 | Addition | Approved |

---
: In Progress - 5 conflicts pending stakeholder resolution
: 2026-02-20
: Will be generated upon completion of all conflict resolutions

Secondary Format (JSON) - Machine Processing and Audit Trail:

{
  "metadata": {
    "project_id": "PROJECT-001",
    "merge_timestamp": "2026-02-15T10:30:00Z",
    "sources": [
      {
        "filename": "requirements-v1.md",
        "requirements_count": 25,
        "format": "markdown"
      },
      {
        "filename": "stakeholder-feedback.docx",
        "requirements_count": 31,
        "format": "docx"
      },
      {
        "filename": "technical-constraints.pdf",
        "requirements_count": 17,
        "format": "pdf"
      
    
     
     
  
   
     
     
     
     
     
     
     
  
   
    
       
       
       
       
       
       
       
        
           
           
           
           
        
        
           
           
           
           
        
      
    
  
   
    
       
       
       
       
       
       
       
        
           
           
           
        
        
            
           
           
        
      
       
       
    
  
   
     
      
         
         
         
         
      
    
     
      
         
         
         
      
    
  
   
     
     
     
     
  
   
     
      
         
         
         
      
      
         
         
         
         
      
    
     
      
         
         
         
      
    
  

Tertiary Format (Markdown) - Conflict Resolution Log for Stakeholder Review:

# Merge Conflicts Resolution Log

**Project**: PROJECT-001
**Generated**: 2026-02-15T10:30:00Z
**Status**: 5 of 8 conflicts require stakeholder resolution

## High Priority Conflicts (Executive Decision Required)

### CR-003: Deployment Architecture Strategy
**Impact Level**: 🔴 **HIGH** - Affects entire technical architecture and cost model
**Sources**: All three requirement documents present different architectural preferences
**Business Impact**: 
- Cost implications: Cloud vs on-premises operational expenses
- Timeline impact: 2-4 months difference in deployment approach
- Scalability constraints: Different growth capacity based on choice
**Technical Impact**:
- Development approach: Cloud-native vs hybrid development patterns
- Integration complexity: Different third-party service integration approaches
- Maintenance overhead: Varying operational support requirements

**Stakeholder Positions**:
- **IT Leadership**: Prefers cloud-native for scalability and maintenance reduction
- **Finance Team**: Concerned about ongoing cloud costs vs capital expenditure
- **Compliance Team**: Requires hybrid approach for sensitive data sovereignty
- **Development Team**: Recommends cloud-native for development velocity

**Recommended Resolution Process**:
1. Executive stakeholder meeting by 2026-02-17
2. Total cost of ownership analysis presentation
3. Risk assessment for each deployment option
4. Final decision and implementation roadmap approval

**Interim Approach**: Continue cloud-native development with deployment flexibility preserved

### CR-001: Authentication Protocol Standards
: 🟡  - Affects security architecture and enterprise integration
: Disagreement on primary authentication protocols
: Architecture Review Board
: 2026-02-20




: 🟡  - Affects development timeline and user experience
: 2026-02-19
: Frontend Architecture Team Lead


: 🟡  - Affects data consistency and performance patterns  
: 2026-02-21
: Database Architecture Team Lead




: Multi-framework support with configuration-based selection
: Development Team Lead (2026-02-14)


: Adopted most restrictive standards from all sources
: Development Team Lead (2026-02-14)


: Highest coverage requirement applied (90% code coverage)
: Quality Assurance Team Lead (2026-02-14)




  (Responsible: Project Manager)
  (Responsible: Finance Team)
  (Responsible: Security Team)


  (Responsible: Frontend Team)
  (Responsible: Backend Team)
  (Responsible: Business Analyst)


  (Responsible: Technical Writer)
  (Responsible: Project Manager)
  (Responsible: Product Owner)

---
: 2026-02-18 at 2:00 PM
: Senior Solution Architect
: This log will be updated as conflicts are resolved

Instructions

1. Multi-Source Requirement Analysis

Source Processing Strategy:

• Format Normalization: Convert all input formats (PDF, DOCX, MD, TXT, etc.) into structured requirement objects
• Semantic Analysis: Use NLP to identify requirement intent, not just textual similarity
• Categorization Consistency: Apply consistent requirement categorization across all sources
• Quality Assessment: Evaluate requirement clarity, completeness, and testability for each source

Requirement Extraction Process:

• Atomic Decomposition: Break complex requirements into atomic, testable components
• Context Preservation: Maintain business context and rationale from original sources
• Dependency Identification: Map dependencies and relationships between requirements
• Priority Inheritance: Preserve or infer requirement priorities from source documents

2. Conflict Detection and Classification

Conflict Types:

• Direct Contradiction: Requirements that explicitly contradict each other
• Priority Mismatch: Same requirement with different priority levels across sources
• Scope Variance: Different interpretations of requirement scope and boundaries
• Implementation Approach: Different technical approaches for achieving same goal
• Quality Attributes: Conflicting non-functional requirements (performance, security, etc.)
• Timeline Conflicts: Requirements with incompatible delivery timeline expectations

Conflict Analysis Process:

• Semantic Similarity: Use NLP to identify semantically similar but conflicting requirements
• Impact Assessment: Evaluate business, technical, and timeline impact of each conflict
• Stakeholder Mapping: Identify which stakeholders are affected by each conflict
• Resolution Complexity: Assess difficulty and resource requirements for conflict resolution

Conflict Prioritization:

• High Priority: Architectural decisions, regulatory requirements, security fundamentals
• Medium Priority: Feature specifications, performance requirements, integration approaches
• Low Priority: Implementation details, tooling choices, coding standards

3. Automatic Conflict Resolution

Auto-Resolution Rules (Conservative Approach):

• Regulatory Compliance: Always choose most restrictive compliance requirement
• Security Standards: Always apply highest security standard when multiple specified
• Performance Metrics: Use most stringent performance requirement that's technically feasible
• Data Quality: Apply highest data quality and integrity standards
• Testing Standards: Adopt most comprehensive testing requirement coverage

Safe Auto-Resolution Criteria:

• Resolution doesn't change fundamental business logic
• No significant cost or timeline impact
• Technical feasibility is confirmed
• Regulatory or security compliance is maintained
• All affected stakeholders would reasonably agree with resolution

Documentation Requirements:

• Log all automatic resolutions with detailed rationale
• Provide rollback mechanism if stakeholders disagree with auto-resolution
• Maintain audit trail for compliance and review purposes

4. Stakeholder-Driven Conflict Resolution

Resolution Workflow:

• Conflict Presentation: Clearly articulate conflict sources, implications, and options
• Impact Analysis: Provide business, technical, cost, and timeline impact assessment
• Recommendation Development: Present recommended resolution with supporting rationale
• Stakeholder Consultation: Facilitate stakeholder discussion and decision-making
• Decision Documentation: Formally record stakeholder decisions and approval

Escalation Framework:

• Team Level: Technical decisions, implementation approaches, minor scope changes
• Architecture Review: System design conflicts, technology stack decisions, major technical patterns
• Business Stakeholders: Feature priorities, business rule conflicts, user experience decisions
• Executive Level: Strategy conflicts, major cost implications, significant timeline impacts

Decision Support Tools:

• Cost-Benefit Analysis: Quantitative impact assessment for each resolution option
• Risk Assessment: Technical, business, and operational risks for different resolution paths
• Prototype Development: When needed, develop prototypes to validate resolution approaches
• Stakeholder Voting: Structured decision-making process for complex multi-stakeholder conflicts

5. Redundancy Elimination with Context Preservation

Redundancy Detection:

• Textual Similarity: Identify requirements with similar wording but potentially different intent
• Functional Equivalence: Detect requirements that achieve the same functional outcome
• Implementation Overlap: Identify requirements that would result in overlapping implementation
• Business Value Duplication: Find requirements targeting identical business outcomes

Intelligent Consolidation:

• Scope Expansion: Merge narrow requirements into broader, more comprehensive specifications
• Quality Enhancement: Combine basic requirements with enhanced quality attributes
• Context Integration: Merge requirements while preserving important contextual variations
• Traceability Preservation: Maintain links to all original sources during consolidation

Variation Preservation Rules:

• Platform Differences: Preserve platform-specific requirements (mobile vs desktop vs web)
• Regional Variations: Maintain region-specific compliance or business rule differences
• User Role Differences: Keep role-specific requirement variations intact
• Implementation Phases: Preserve requirements that apply to different implementation phases

6. Unified Specification Generation

Content Organization Strategy:

• Hierarchical Structure: Organize by business domain, then functional area, then specific requirements
• Cross-Cutting Concerns: Handle quality attributes, security, and performance as cross-cutting themes
• Dependencies and Relationships: Clearly document requirement dependencies and interaction patterns
• Prioritization Integration: Integrate priority levels and phasing information into unified structure

Quality Standards for Unified Output:

• Consistency: Uniform terminology, formatting, and specification patterns
• Completeness: All original requirement intent preserved and addressed
• Clarity: Clear, unambiguous language accessible to all stakeholders
• Testability: All requirements specified in testable, verifiable terms
• Traceability: Complete mapping between unified requirements and original sources

Format Optimization:

• Stakeholder-Specific Views: Generate different views optimized for different stakeholder needs
• Machine Processing: Provide structured formats suitable for automated processing
• Review Workflows: Optimize format for stakeholder review and approval processes
• Integration Ready: Format suitable for integration with project planning and development tools

Integration Points

Upstream Skills:

• requirements-ingest: Process and normalize individual requirement sources before merging
• goals-extract: Business objectives inform conflict resolution priorities and decisions
• process-w5h: Stakeholder analysis guides conflict escalation and resolution workflows
• domain-extractconcepts: Domain terminology consistency supports merge quality

Downstream Skills:

• process-scopemin: Unified requirements feed into scope minimization and MVP planning
• project-planning-tracking: Conflict resolution timelines integrate with overall project schedules
• diagram-generatecollaboration: Unified requirements inform system interaction modeling
• change-management: Requirement changes and conflict resolutions trigger change management

Collaboration Skills:

• domain-alignentities: Ensure merged requirements maintain domain architecture consistency
• project-status-reporting: Merge progress and conflict resolution status feed into project reporting
• project-document-management: Unified specifications integrate with project documentation structure

Quality Assurance

Validation Checklist

Merge Completeness:

• All source requirements addressed in unified specification
• No requirements accidentally dropped or omitted during merge process
• All stakeholder concerns and feedback incorporated appropriately
• Complete traceability maintained from sources to unified requirements

Conflict Resolution Quality:

• All conflicts identified and categorized appropriately
• Auto-resolution rules applied consistently and conservatively
• Stakeholder conflicts escalated to appropriate decision-making level
• Resolution rationale documented and stakeholder-approved

Specification Quality:

• Unified requirements are clear, testable, and unambiguous
• Terminology is consistent throughout specification
• Dependencies and relationships clearly documented
• Priority levels and phasing information integrated consistently

Stakeholder Workflow:

• All affected stakeholders identified and engaged in conflict resolution
• Review and approval workflows completed as specified
• Stakeholder decisions formally documented and signed off
• Conflict resolution timeline adhered to and tracked

Success Metrics

Process Effectiveness:

• Merge completion time (target: 2-5 business days for typical projects)
• Conflict resolution rate (target: >90% within initial stakeholder review cycle)
• Stakeholder approval rate for unified specifications (target: >95%)
• Requirement traceability accuracy (target: 100% traceable)

Quality Outcomes:

• Reduction in downstream requirement clarification requests (target: >70% reduction)
• Stakeholder satisfaction with unified specification quality (target: >90% satisfaction)
• Development team clarity on requirements (target: <5% implementation questions)
• Post-implementation requirement change rate (target: <10% post-merge changes)

Business Impact:

• Requirements phase duration optimization (target: 20-30% time reduction)
• Development velocity improvement due to requirement clarity
• Stakeholder alignment and conflict reduction in subsequent project phases
• Project risk reduction through early conflict identification and resolution

---

This skill provides comprehensive requirements merging capabilities that enable complex multi-stakeholder projects to achieve unified, coherent requirement specifications while maintaining stakeholder alignment and project governance standards.