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.

Intent

Merge requirements from two or more heterogeneous sources into one unified, coherent specification. Detect conflicts and redundancies, resolve them per the chosen strategy, and maintain full source traceability for stakeholder review and compliance audit.

Inputs

• Source documents: Two or more requirements files (PDF, DOCX, Markdown, or requirements.json from requirements-ingest)
• Project ID: project_id
• Optional: merge_strategy — conservative (manual review for all conflicts) | comprehensive (auto-resolve low-confidence conflicts, default)

Outputs

• outputs/projects/{project_id}/Analysis/unified-requirements.md — Merged specification (primary, for downstream skills)
• outputs/projects/{project_id}/Analysis/merge-analysis.json — Detailed merge trace with source traceability
• outputs/projects/{project_id}/Analysis/merge-conflicts.md — Conflict log for stakeholder review

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.