Change Management

Transforms AI conversation text and requirement discussions into structured change documents with automatic classification, impact analysis, and reference updates.

Core Function

Input: Conversation text + project context + change scope
Output: Structured change document + affected file list + reference updates

Usage

GitHub Copilot Integration (Recommended):

Use this skill directly in Copilot by providing conversation text that contains requirement changes.
Copilot will automatically identify changes, classify them, and generate proper documentation.

Example prompt:
"Use change-management skill to analyze this conversation for requirement changes and create proper change documentation with impact analysis and reference updates."

Traditional Script Approach:

from change_management import ChangeProcessor
processor = ChangeProcessor()
result = processor.process_conversation(text=conversation_text, project_id="PRJ-001")

Output Schema

ALWAYS return exactly this JSON structure:

{
  "project_id": "string",
  "changes_identified": [
    {
      "change_id": "PROC-CHG-001", 
      "change_type": "REQ-CHG|REQ-ADD|REQ-REM|SCOPE-CHG|PROC-CHG",
      "title": "Brief description for filename",
      "summary": "One-line change summary",
      "priority": "Low|Medium|High|Critical",
      "status": "Proposed",
      "rationale": "Why this change is needed",
      "current_state": "Description of current requirement/process",
      "proposed_state": "Description after change",
      "impact_analysis": {
        "affected_documents": [
          {
            "file_path": "relative/path/to/file.md",
            "impact_description": "How this file is affected",
            "update_required": true
          }
        ],
        "affected_tasks": [
          {
            "task_id": "T2",
            "impact_description": "How this task is affected"
          }
        ],
        "risk_level": "Low|Medium|High",
        "estimated_effort": "X hours/days"
      }
    }
  ],
  "reference_updates": [
    {
      "file_path": "relative/path/to/file.md",
      "section": "Related Changes",
      "new_reference": "- [PROC-CHG-001](../artifacts/Changes/2026-02-08-PROC-CHG-001-title.md) - Description"
    }
  ],
  "next_actions": [
    "Action item 1",
    "Action item 2"
  ]
}

GitHub Copilot Integration

Direct Usage in Copilot Chat

Paste your conversation or discussion text and ask:

@workspace Use the change-management skill to process this conversation:

[PASTE CONVERSATION TEXT HERE]

Project ID: AI-SLOWCOOKER-001
Context: Building Skills project

Identify requirement changes and:
- Classify change types (REQ-CHG, PROC-CHG, etc.)
- Generate impact analysis
- Create proper change documentation
- Identify files needing reference updates
- Suggest next actions

Return structured JSON following the schema.

Copilot Prompt Template

Analyze conversation using change-management methodology:

1. IDENTIFY: Scan for explicit/implicit requirement changes
2. CLASSIFY: Categorize as REQ-CHG|REQ-ADD|REQ-REM|SCOPE-CHG|PROC-CHG
3. ANALYZE: Assess impact on documents, tasks, orgModel files
4. DOCUMENT: Generate structured change document content
5. REFERENCE: Identify files needing reference updates

Output exact JSON schema with changes_identified, reference_updates, next_actions.

Classification Rules

Change Types

REQ-CHG: Modifications to existing requirements
REQ-ADD: New requirements added to project scope
REQ-REM: Requirements removed or marked obsolete
SCOPE-CHG: Project scope adjustments (budget, timeline, deliverables)
PROC-CHG: Development process or workflow modifications

Priority Assessment

Critical: Blocks progress, affects core functionality
High: Significant impact on project deliverables
Medium: Moderate impact, can be scheduled normally
Low: Minor impact, can be deferred

Project Phase Context

Planning Phase: Changes have higher flexibility, lower implementation cost
Development Phase: Changes require careful impact assessment, may affect timeline
Testing Phase: Changes should be minimal, focus on critical fixes only
Deployment Phase: Only critical changes allowed, require stakeholder approval

Risk Levels

Low: Minimal impact, easy implementation
Medium: Some complexity, moderate impact
High: Significant impact, complex implementation

Processing Rules

Change Detection: Identify explicit statements ("we need to change") and implicit changes ("actually, it should...")
Context Awareness: Consider project phase, existing constraints, stakeholder roles
Impact Analysis: Evaluate effects on requirements, tasks, process models, timeline
Traceability: Maintain links between changes and affected components
File Naming: Generate proper filename using format YYYY-MM-DD-{TYPE}-{ID}-{title}.md

Reference Path Patterns

From Tasks to Changes: ../artifacts/Changes/
From OrgModel to Changes: ../../projects/{project-name}/artifacts/Changes/
From Project Root to Changes: artifacts/Changes/

Change ID Management

Sequential ID Generation

Scan Existing Changes: Check artifacts/Changes/ directory for highest ID number per type
Auto-Increment Logic: Generate next available ID within change type
Conflict Prevention: Verify ID uniqueness before document creation
Cross-Reference Check: Ensure ID not used in any related project files

ID Format Rules

Pattern: {TYPE}-CHG-{###} where ### is zero-padded 3-digit number
Examples: REQ-CHG-001, SCOPE-CHG-015, PROC-CHG-003
Numbering: Sequential within each change type, starting from 001

Implementation Algorithm

def generate_change_id(change_type, changes_directory):
    # Scan existing change files for this type
    existing_ids = scan_change_files(changes_directory, change_type)
    # Find highest number
    max_id = max([extract_id_number(id) for id in existing_ids], default=0)
    # Generate next ID
    next_id = f"{change_type}-CHG-{str(max_id + 1).zfill(3)}"
    # Verify uniqueness across all files
    verify_id_uniqueness(next_id, project_directory)
    return next_id

Quality Checks

Change ID Uniqueness:
- Scan all existing change documents for ID conflicts
- Verify ID follows proper format pattern
- Check cross-references in tasks, requirements, and orgModel files
Impact Completeness:
- Every affected document must have specific impact description
- Risk level must align with scope of affected components
- Effort estimation must consider cascading effects
- Missing dependencies must be flagged as incomplete
Reference Accuracy:
- Validate all relative paths resolve correctly from target locations
- Ensure markdown links use proper encoding for spaces/special chars
- Verify referenced files actually exist in project structure
Documentation Standards:
- Title length must be under 80 characters for filename compatibility
- Summary must be single line, under 120 characters
- Rationale must explain business/technical justification
Status Consistency:
- New changes default to "Proposed" status
- Status progression follows: Proposed → Approved → Implemented → Verified
- Critical changes require immediate stakeholder notification

Integration Points

Requirements Ingest: Changes may trigger re-ingestion of modified requirements
Task Planning: New changes may spawn additional tasks or modify existing ones
Status Reporting: Changes feed into project status and progress tracking
Document Management: Changes integrate with overall project documentation structure

AI Conversation Patterns

Detection Signals

"We need to change..." / "Actually, we should..."
"I think the requirement should be..." / "Let me clarify..."
"Instead of X, we need Y..." / "This doesn't work because..."
"Add to the scope..." / "Remove from the scope..."
"The process should..." / "Our workflow needs..."

Context Clues

Reference to existing requirement documents
Discussion of implementation challenges
Stakeholder feedback incorporation
Technical constraint discoveries
Business priority adjustments

Error Handling & Validation

Input Validation

Ambiguous Changes: When conversation contains unclear requirements
- Flag as "Needs Clarification" status
- Generate follow-up questions for stakeholders
- Document assumptions made and validation needed
Incomplete Context: When project context is insufficient
- Request additional project information
- Use conservative impact assessment
- Mark analysis as "Preliminary - Requires Project Context"
Conflicting Information: When conversation contains contradictions
- Document all conflicting statements
- Flag for stakeholder resolution
- Do not auto-classify until clarified

Validation Rules

Minimum Required Information:
- Change description (explicit or derivable from context)
- Affected component identification (documents/tasks/processes)
- Business rationale (stated or reasonably inferred)
Quality Thresholds:
- Impact analysis must identify at least 1 affected component
- Risk assessment must align with scope (High risk = multiple components)
- Effort estimation must be within reasonable bounds (1 hour - 2 weeks)
Cross-Reference Validation:
- All mentioned files must exist in project structure
- Task references must match existing task IDs
- Path references must be valid from multiple locations

Error Recovery

Missing Information: Generate change document with placeholders and flag sections needing input
Invalid References: Log broken references and suggest corrections
ID Conflicts: Auto-increment to next available ID and document conflict resolution

File Generation

The skill generates change documents following this template structure:

# Change Title

**Change ID**: {TYPE}-{###}  
**Date Created**: {YYYY-MM-DD}  
**Status**: Proposed  
**Priority**: {Level}  
**Requested By**: [Extracted from context]

## Summary
{One-line description}

## Change Details
{Detailed description extracted from conversation}

### Current State
{Current situation description}

### Proposed State  
{Desired future state}

### Rationale
{Why change is needed}

## Impact Analysis
{Generated impact assessment}

## Implementation Plan
{Suggested implementation steps}

## Acceptance Criteria
{Generated success criteria}