trent_larson
/
crowd-funder-for-time-pwa
4
1
Fork 2
Code Issues Pull Requests 17 Releases 5 Wiki Activity
Browse Source

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.
profile_include_location
Matthew Raymer 2 weeks ago
parent
77a4c60656
commit
b834596ba6
1 changed files with 383 additions and 0 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 383
      .cursor/rules/meta_change_evaluation.mdc

383
.cursor/rules/meta_change_evaluation.mdc
View 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
Write Preview
Loading…
Cancel
Save