granular_backtest/.cursor/rules/refactoring.mdc

---
description: Code refactoring and technical debt management for AI-assisted development
globs: 
alwaysApply: false
---

# Rule: Code Refactoring and Technical Debt Management

## Goal
Guide AI in systematic code refactoring to improve maintainability, reduce complexity, and prevent technical debt accumulation in AI-assisted development projects.

## When to Apply This Rule
- Code complexity has increased beyond manageable levels
- Duplicate code patterns are detected
- Performance issues are identified
- New features are difficult to integrate
- Code review reveals maintainability concerns
- Weekly technical debt assessment indicates refactoring needs

## Pre-Refactoring Assessment

Before starting any refactoring, the AI MUST:

1. **Context Analysis:**
   - Review existing `CONTEXT.md` for architectural decisions
   - Analyze current code patterns and conventions
   - Identify all files that will be affected (search the codebase for use)
   - Check for existing tests that verify current behavior

2. **Scope Definition:**
   - Clearly define what will and will not be changed
   - Identify the specific refactoring pattern to apply
   - Estimate the blast radius of changes
   - Plan rollback strategy if needed

3. **Documentation Review:**
   - Check `./docs/` for relevant module documentation
   - Review any existing architectural diagrams
   - Identify dependencies and integration points
   - Note any known constraints or limitations

## Refactoring Process

### Phase 1: Planning and Safety
1. **Create Refactoring Plan:**
   - Document the current state and desired end state
   - Break refactoring into small, atomic steps
   - Identify tests that must pass throughout the process
   - Plan verification steps for each change

2. **Establish Safety Net:**
   - Ensure comprehensive test coverage exists
   - If tests are missing, create them BEFORE refactoring
   - Document current behavior that must be preserved
   - Create backup of current implementation approach

3. **Get Approval:**
   - Present the refactoring plan to the user
   - Wait for explicit "Go" or "Proceed" confirmation
   - Do NOT start refactoring without approval

### Phase 2: Incremental Implementation
4. **One Change at a Time:**
   - Implement ONE refactoring step per iteration
   - Run tests after each step to ensure nothing breaks
   - Update documentation if interfaces change
   - Mark progress in the refactoring plan

5. **Verification Protocol:**
   - Run all relevant tests after each change
   - Verify functionality works as expected
   - Check performance hasn't degraded
   - Ensure no new linting or type errors

6. **User Checkpoint:**
   - After each significant step, pause for user review
   - Present what was changed and current status
   - Wait for approval before continuing
   - Address any concerns before proceeding

### Phase 3: Completion and Documentation
7. **Final Verification:**
   - Run full test suite to ensure nothing is broken
   - Verify all original functionality is preserved
   - Check that new code follows project conventions
   - Confirm performance is maintained or improved

8. **Documentation Update:**
   - Update `CONTEXT.md` with new patterns/decisions
   - Update module documentation in `./docs/`
   - Document any new conventions established
   - Note lessons learned for future refactoring

## Common Refactoring Patterns

### Extract Method/Function
```
WHEN: Functions/methods exceed 50 lines or have multiple responsibilities
HOW: 
1. Identify logical groupings within the function
2. Extract each group into a well-named helper function
3. Ensure each function has a single responsibility
4. Verify tests still pass
```

### Extract Module/Class
```
WHEN: Files exceed 250 lines or handle multiple concerns
HOW:
1. Identify cohesive functionality groups
2. Create new files for each group
3. Move related functions/classes together
4. Update imports and dependencies
5. Verify module boundaries are clean
```

### Eliminate Duplication
```
WHEN: Similar code appears in multiple places
HOW:
1. Identify the common pattern or functionality
2. Extract to a shared utility function or module
3. Update all usage sites to use the shared code
4. Ensure the abstraction is not over-engineered
```

### Improve Data Structures
```
WHEN: Complex nested objects or unclear data flow
HOW:
1. Define clear interfaces/types for data structures
2. Create transformation functions between different representations
3. Ensure data flow is unidirectional where possible
4. Add validation at boundaries
```

### Reduce Coupling
```
WHEN: Modules are tightly interconnected
HOW:
1. Identify dependencies between modules
2. Extract interfaces for external dependencies
3. Use dependency injection where appropriate
4. Ensure modules can be tested in isolation
```

## Quality Gates

Every refactoring must pass these gates:

### Technical Quality
- [ ] All existing tests pass
- [ ] No new linting errors introduced
- [ ] Code follows established project conventions
- [ ] No performance regression detected
- [ ] File sizes remain under 250 lines
- [ ] Function sizes remain under 50 lines

### Maintainability
- [ ] Code is more readable than before
- [ ] Duplicated code has been reduced
- [ ] Module responsibilities are clearer
- [ ] Dependencies are explicit and minimal
- [ ] Error handling is consistent

### Documentation
- [ ] Public interfaces are documented
- [ ] Complex logic has explanatory comments
- [ ] Architectural decisions are recorded
- [ ] Examples are provided where helpful

## AI Instructions for Refactoring

1. **Always ask for permission** before starting any refactoring work
2. **Start with tests** - ensure comprehensive coverage before changing code
3. **Work incrementally** - make small changes and verify each step
4. **Preserve behavior** - functionality must remain exactly the same
5. **Update documentation** - keep all docs current with changes
6. **Follow conventions** - maintain consistency with existing codebase
7. **Stop and ask** if any step fails or produces unexpected results
8. **Explain changes** - clearly communicate what was changed and why

## Anti-Patterns to Avoid

### Over-Engineering
- Don't create abstractions for code that isn't duplicated
- Avoid complex inheritance hierarchies
- Don't optimize prematurely

### Breaking Changes
- Never change public APIs without explicit approval
- Don't remove functionality, even if it seems unused
- Avoid changing behavior "while we're here"

### Scope Creep
- Stick to the defined refactoring scope
- Don't add new features during refactoring
- Resist the urge to "improve" unrelated code

## Success Metrics

Track these metrics to ensure refactoring effectiveness:

### Code Quality
- Reduced cyclomatic complexity
- Lower code duplication percentage
- Improved test coverage
- Fewer linting violations

### Developer Experience
- Faster time to understand code
- Easier integration of new features
- Reduced bug introduction rate
- Higher developer confidence in changes

### Maintainability
- Clearer module boundaries
- More predictable behavior
- Easier debugging and troubleshooting
- Better performance characteristics

## Output Files

When refactoring is complete, update:
- `refactoring-log-[date].md` - Document what was changed and why
- `CONTEXT.md` - Update with new patterns and decisions
- `./docs/` - Update relevant module documentation
- Task lists - Mark refactoring tasks as complete

## Final Verification

Before marking refactoring complete:
1. Run full test suite and verify all tests pass
2. Check that code follows all project conventions
3. Verify documentation is up to date
4. Confirm user is satisfied with the results
5. Record lessons learned for future refactoring efforts