diff --git a/.cursor/rules/meta_change_evaluation.mdc b/.cursor/rules/meta_change_evaluation.mdc new file mode 100644 index 00000000..dd4e1f74 --- /dev/null +++ b/.cursor/rules/meta_change_evaluation.mdc @@ -0,0 +1,383 @@ +# 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): 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