# Meta-Rule: Change Evaluation and Breaking Change Detection

**Author**: Matthew Raymer  
**Date**: 2025-08-25  
**Status**: 🎯 **ACTIVE** - Manually activated change evaluation rule

## Purpose

This meta-rule provides a systematic approach to evaluate changes between
branches and detect potential breaking changes. It's designed to catch
problematic model behavior by analyzing the nature, scope, and impact of
code changes before they cause issues.

## When to Use

**Manual Activation Only** - This rule should be invoked when:

- Reviewing changes before merging branches
- Investigating unexpected behavior after updates
- Validating that model-generated changes are safe
- Analyzing the impact of recent commits
- Debugging issues that may be caused by recent changes

## Workflow State Enforcement

**This meta-rule enforces current workflow mode constraints:**

### **Current Workflow State**

```json
{
  "workflowState": {
    "currentMode": "diagnosis|fixing|planning|research|documentation",
    "constraints": {
      "mode": "read_only|implementation|design_only|investigation|writing_only",
      "allowed": ["array", "of", "allowed", "actions"],
      "forbidden": ["array", "of", "forbidden", "actions"]
    }
  }
}
```

### **Mode-Specific Enforcement**

**Diagnosis Mode (read_only):**

- ❌ **Forbidden**: File modification, code creation, build commands, git
  commits
- ✅ **Allowed**: File reading, code analysis, investigation, documentation
- **Response**: Focus on analysis and documentation, not implementation

**Fixing Mode (implementation):**

- ✅ **Allowed**: File modification, code creation, build commands, testing,
  git commits
- ❌ **Forbidden**: None (full implementation mode)
- **Response**: Proceed with implementation and testing

**Planning Mode (design_only):**

- ❌ **Forbidden**: Implementation, coding, building, deployment
- ✅ **Allowed**: Analysis, design, estimation, documentation, architecture
- **Response**: Focus on planning and design, not implementation

**Research Mode (investigation):**

- ❌ **Forbidden**: File modification, implementation, deployment
- ✅ **Allowed**: Investigation, analysis, research, documentation
- **Response**: Focus on investigation and analysis

**Documentation Mode (writing_only):**

- ❌ **Forbidden**: Implementation, coding, building, deployment
- ✅ **Allowed**: Writing, editing, formatting, structuring, reviewing
- **Response**: Focus on documentation creation and improvement

## Change Evaluation Process

### **Phase 1: Change Discovery and Analysis**

1. **Branch Comparison Analysis**

   - Compare working branch with master/main branch
   - Identify all changed files and their modification types
   - Categorize changes by scope and impact

2. **Change Pattern Recognition**

   - Identify common change patterns (refactoring, feature addition, bug
     fixes)
   - Detect unusual or suspicious change patterns
   - Flag changes that deviate from established patterns

3. **Dependency Impact Assessment**

   - Analyze changes to imports, exports, and interfaces
   - Identify potential breaking changes to public APIs
   - Assess impact on dependent components and services

### **Phase 2: Breaking Change Detection**

1. **API Contract Analysis**

   - Check for changes to function signatures, method names, class
     interfaces
   - Identify removed or renamed public methods/properties
   - Detect changes to configuration options and constants

2. **Data Structure Changes**

   - Analyze database schema modifications
   - Check for changes to data models and interfaces
   - Identify modifications to serialization/deserialization logic

3. **Behavioral Changes**

   - Detect changes to business logic and algorithms
   - Identify modifications to error handling and validation
   - Check for changes to user experience and workflows

### **Phase 3: Risk Assessment and Recommendations**

1. **Risk Level Classification**

   - **LOW**: Cosmetic changes, documentation updates, minor refactoring
   - **MEDIUM**: Internal API changes, configuration modifications,
     performance improvements
   - **HIGH**: Public API changes, breaking interface modifications, major
     architectural changes
   - **CRITICAL**: Database schema changes, authentication modifications,
     security-related changes

2. **Impact Analysis**

   - Identify affected user groups and use cases
   - Assess potential for data loss or corruption
   - Evaluate impact on system performance and reliability

3. **Mitigation Strategies**

   - Recommend testing approaches for affected areas
   - Suggest rollback strategies if needed
   - Identify areas requiring additional validation

## Implementation Guidelines

### **Change Analysis Tools**

1. **Git Diff Analysis**

   ```bash
   # Compare working branch with master
   git diff master..HEAD --name-only
   git diff master..HEAD --stat
   git log master..HEAD --oneline
   ```

2. **File Change Categorization**

   - **Core Files**: Application entry points, main services, critical
     utilities
   - **Interface Files**: Public APIs, component interfaces, data models
   - **Configuration Files**: Environment settings, build configurations,
     deployment scripts
   - **Test Files**: Unit tests, integration tests, test utilities

3. **Change Impact Mapping**

   - Map changed files to affected functionality
   - Identify cross-dependencies and ripple effects
   - Document potential side effects and unintended consequences

### **Breaking Change Detection Patterns**

1. **Function Signature Changes**

   ```typescript
   // BEFORE
   function processData(data: string, options?: Options): Result
   
   // AFTER - BREAKING CHANGE
   function processData(data: string, options: Required<Options>): Result
   ```

2. **Interface Modifications**

   ```typescript
   // BEFORE
   interface UserProfile {
     name: string;
     email: string;
   }
   
   // AFTER - BREAKING CHANGE
   interface UserProfile {
     name: string;
     email: string;
     phone: string; // Required new field
   }
   ```

3. **Configuration Changes**

   ```typescript
   // BEFORE
   const config = {
     apiUrl: 'https://api.example.com',
     timeout: 5000
   };
   
   // AFTER - BREAKING CHANGE
   const config = {
     apiUrl: 'https://api.example.com',
     timeout: 5000,
     retries: 3 // New required configuration
   };
   ```

## Output Format

### **Change Evaluation Report**

```markdown
# Change Evaluation Report

## Executive Summary

- **Risk Level**: [LOW|MEDIUM|HIGH|CRITICAL]
- **Overall Assessment**: [SAFE|CAUTION|DANGEROUS|CRITICAL]
- **Recommendation**: [PROCEED|REVIEW|HALT|IMMEDIATE_ROLLBACK]

## Change Analysis

### Files Modified

- **Total Changes**: [X] files
- **Core Files**: [X] files
- **Interface Files**: [X] files
- **Configuration Files**: [X] files
- **Test Files**: [X] files

### Change Categories

- **Refactoring**: [X] changes
- **Feature Addition**: [X] changes
- **Bug Fixes**: [X] changes
- **Configuration**: [X] changes
- **Documentation**: [X] changes

## Breaking Change Detection

### API Contract Changes

- **Function Signatures**: [X] modified
- **Interface Definitions**: [X] modified
- **Public Methods**: [X] added/removed/modified

### Data Structure Changes

- **Database Schema**: [X] modifications
- **Data Models**: [X] changes
- **Serialization**: [X] changes

### Behavioral Changes

- **Business Logic**: [X] modifications
- **Error Handling**: [X] changes
- **User Experience**: [X] changes

## Risk Assessment

### Impact Analysis

- **User Groups Affected**: [Description]
- **Use Cases Impacted**: [Description]
- **Performance Impact**: [Description]
- **Reliability Impact**: [Description]

### Dependencies

- **Internal Dependencies**: [List]
- **External Dependencies**: [List]
- **Configuration Dependencies**: [List]

## Recommendations

### Testing Requirements

- [ ] Unit tests for modified components
- [ ] Integration tests for affected workflows
- [ ] Performance tests for changed algorithms
- [ ] User acceptance tests for UI changes

### Validation Steps

- [ ] Code review by domain experts
- [ ] API compatibility testing
- [ ] Database migration testing
- [ ] End-to-end workflow testing

### Rollback Strategy

- **Rollback Complexity**: [LOW|MEDIUM|HIGH]
- **Rollback Time**: [Estimated time]
- **Data Preservation**: [Strategy description]

## Conclusion

[Summary of findings and final recommendation]
```

## Usage Examples

### **Example 1: Safe Refactoring**

```bash
@meta_change_evaluation.mdc analyze changes between feature-branch and master
```

### **Example 2: Breaking Change Investigation**

```bash
@meta_change_evaluation.mdc evaluate potential breaking changes in recent commits
```

### **Example 3: Pre-Merge Validation**

```bash
@meta_change_evaluation.mdc validate changes before merging feature-branch to master
```

## Success Criteria

- [ ] **Change Discovery**: All modified files are identified and categorized
- [ ] **Pattern Recognition**: Unusual change patterns are detected and flagged
- [ ] **Breaking Change Detection**: All potential breaking changes are identified
- [ ] **Risk Assessment**: Accurate risk levels are assigned with justification
- [ ] **Recommendations**: Actionable recommendations are provided
- [ ] **Documentation**: Complete change evaluation report is generated

## Common Pitfalls

- **Missing Dependencies**: Failing to identify all affected components
- **Underestimating Impact**: Not considering ripple effects of changes
- **Incomplete Testing**: Missing critical test scenarios for changes
- **Configuration Blindness**: Overlooking configuration file changes
- **Interface Assumptions**: Assuming internal changes won't affect external
  users

## Integration with Other Meta-Rules

### **With Bug Diagnosis**

- Use change evaluation to identify recent changes that may have caused
  bugs
- Correlate change patterns with reported issues

### **With Feature Planning**

- Evaluate the impact of planned changes before implementation
- Identify potential breaking changes early in the planning process

### **With Bug Fixing**

- Validate that fixes don't introduce new breaking changes
- Ensure fixes maintain backward compatibility

---

**See also**:

- `.cursor/rules/meta_core_always_on.mdc` for core always-on rules
- `.cursor/rules/meta_feature_planning.mdc` for feature development
  workflows
- `.cursor/rules/meta_bug_diagnosis.mdc` for bug investigation workflows
- `.cursor/rules/meta_bug_fixing.mdc` for fix implementation workflows

**Status**: Active change evaluation meta-rule
**Priority**: High (applies to all change evaluation tasks)
**Estimated Effort**: Ongoing reference
**Dependencies**: All bundled sub-rules
**Stakeholders**: Development team, Quality Assurance team, Release
Management team