You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
383 lines
11 KiB
383 lines
11 KiB
# 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
|
|
|