forked from trent_larson/crowd-funder-for-time-pwa
feat(meta-rules): create change evaluation and breaking change detection rule
- Create comprehensive meta-rule for evaluating changes between branches - Implement systematic breaking change detection for API contracts, data structures, and behavior - Add risk assessment framework with LOW/MEDIUM/HIGH/CRITICAL classification - Include change pattern recognition and dependency impact assessment - Provide structured output format for change evaluation reports - Apply markdown core standards for consistent formatting and readability Problem: Need systematic approach to catch problematic model behavior by analyzing changes before they cause issues. Solution: Create meta-rule that evaluates changes between branches, detects breaking changes, assesses risk levels, and provides actionable recommendations. Files changed: - .cursor/rules/meta_change_evaluation.mdc: New meta-rule with comprehensive change evaluation capabilities Testing: Rule provides structured approach for analyzing changes, detecting breaking changes, and generating risk assessment reports.
This commit is contained in:
Matthew Raymer
383
.cursor/rules/meta_change_evaluation.mdc
Normal file
383
.cursor/rules/meta_change_evaluation.mdc
Normal file
@@ -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<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
|
||||
Reference in New Issue
Block a user