Instruction file imported from cao117/CFAMasterClerkEntryToolA1.0 (.cursor/rules/codedeletion.mdc). Copyright stays with the author.

Cursor AI Safe Code Removal Guide

Core Principle: Remove Systematically, Preserve Functionality

When removing legacy code or deprecated features, ALWAYS follow a systematic approach that preserves existing functionality while safely eliminating unwanted code.

Pre-Removal Discovery

1. Identify All Related Code

Search for all references to the functionality being removed:

// Search patterns to identify all related code:
// - Variable names and function names to be removed
// - Component names or state variables
// - localStorage keys or configuration settings
// - Modal/UI components for removed features
// - Event handlers or useEffect hooks
// - Type definitions or interfaces
// - Import/export statements

2. Dependency Mapping Checklist

Before removal, identify:

• All files that import or reference the code to be removed
• All components that depend on the functionality
• All state variables and hooks related to the feature
• All localStorage/sessionStorage keys used
• All UI components (modals, forms, buttons) related to the feature
• All routing or navigation logic involved
• All type definitions and interfaces that will become unused

Safe Removal Strategies

1. Incremental Removal Pattern

Remove code in logical dependency order:

// Step 1: Remove UI components and event handlers
// Step 2: Remove state management and hooks  
// Step 3: Remove utility functions and helpers
// Step 4: Remove type definitions and constants
// Step 5: Clean up imports and exports

2. Preserve-First Approach

Always preserve working functionality:

// ✅ DO: Isolate and preserve working code
export function preservedFunction(params) {
  // Keep existing logic that works
  const workingResult = existingWorkingLogic(params);
  
  // Remove only the specific unwanted part
  // if (featureToRemove) { ... } // REMOVE THIS BLOCK ONLY
  
  return workingResult;
}

// ❌ DON'T: Remove entire functions that have mixed functionality

3. Component Isolation Strategy

For React components with mixed functionality:

// ✅ DO: Remove specific features while preserving component
function ExistingComponent() {
  // Keep working state and logic
  const [workingState, setWorkingState] = useState();
  
  // Remove deprecated state
  // const [removedFeature, setRemovedFeature] = useState(); // REMOVE
  
  // Keep working effects
  useEffect(() => {
    // Existing functionality to preserve
  }, []);
  
  // Remove deprecated effects
  // useEffect(() => { deprecated logic }, []); // REMOVE
  
  return (
    <div>
      {/* Keep working UI elements */}
      {/* Remove deprecated UI elements */}
    </div>
  );
}

Systematic Removal Workflow

Step 1: Remove UI Layer

1. Remove deprecated modal components and their trigger logic
2. Remove form fields and input handlers for deprecated features
3. Remove buttons, links, and navigation for removed functionality
4. Remove related CSS classes and styling
5. Remove any conditional rendering logic for removed features

Step 2: Remove State Management

1. Remove useState declarations for deprecated features
2. Remove useEffect hooks specific to removed functionality
3. Remove event handlers and callback functions
4. Remove context providers/consumers for deprecated features
5. Remove Redux actions/reducers (if applicable)

Step 3: Remove Business Logic

1. Remove utility functions specific to removed functionality
2. Remove API calls and data fetching for deprecated features
3. Remove validation logic for removed features
4. Remove data transformation functions that are no longer needed

Step 4: Remove Data Layer

1. Remove localStorage/sessionStorage operations for deprecated features
2. Remove configuration settings and constants
3. Remove database queries or API endpoints (if applicable)
4. Remove data models or interfaces specific to removed functionality

Step 5: Clean Up Dependencies

1. Remove unused imports from all modified files
2. Remove unused type definitions and interfaces
3. Update barrel exports and index files
4. Remove orphaned files that are no longer referenced
5. Clean up any remaining dead code

Verification After Each Step

Immediate Verification:

• App loads successfully without console errors
• Existing functionality works as expected
• No broken imports or reference errors
• No orphaned UI elements or broken links
• No TypeScript compilation errors

Functional Testing:

• Core features continue to work normally
• Navigation and routing remain functional
• Settings and preferences for other features still work
• Data persistence (localStorage/sessionStorage) works for remaining features

Documentation Updates

Update All Relevant Documentation

After successful removal, update:

1. Technical Documentation

• README.md - Remove references to deprecated features
• API documentation - Remove endpoints or parameters that no longer exist
• Component documentation - Remove prop descriptions for deleted components
• Configuration guides - Remove setup instructions for removed features
• Type documentation - Remove JSDoc for deleted interfaces

2. User-Facing Documentation

• User manuals - Remove instructions for deleted features
• Feature guides - Archive or remove guides for removed functionality
• FAQ sections - Remove questions about deprecated features
• Getting started guides - Update onboarding flows
• Troubleshooting guides - Remove error solutions for deleted features

3. Code Documentation

• Code comments - Remove or update comments referencing removed code
• Inline documentation - Update function and component descriptions
• Architecture notes - Update any design documentation

Update Project Tracking

1. Release Documentation

• Changelog entries - Document removed features with clear descriptions
• Release notes - Communicate feature removals to stakeholders
• Migration guides - Provide guidance if users need alternatives

2. Update All Other Relevant Documentation

• Project documentation - Update any project-specific docs that reference removed features
• Development documentation - Update build guides, development setup docs
• Deployment documentation - Update deployment scripts or configuration docs
• Testing documentation - Remove test cases for deleted features
• Design documentation - Update wireframes, mockups, or design specs
• Business documentation - Update requirements docs, feature specs
• Training materials - Update any training docs or onboarding materials
• External documentation - Update public-facing docs, wikis, or help sites

Common Removal Anti-Patterns

❌ Avoid These Mistakes:

1. Mass deletion without dependency checking - Always map dependencies first
2. Removing shared utilities - Check if functions are used by other features
3. Leaving orphaned references - Search for all usages before deletion
4. Not testing incrementally - Verify app works after each removal step
5. Ignoring TypeScript errors - Fix all compilation issues immediately
6. Forgetting localStorage cleanup - Remove unused persisted data
7. Not updating documentation - Keep docs synchronized with code changes
8. Removing error handling - Preserve error boundaries and fallbacks

Enhancement During Removal

Opportunity for Improvement

While removing code, look for opportunities to:

// ✅ DO: Simplify remaining code during removal
function simplifiedFunction(params) {
  // If removing conditions makes logic simpler:
  // Before: if (removedFeature) { ... } else { return result; }
  // After: return result; // Much cleaner!
  
  return simplifiedResult(params);
}

// ✅ DO: Consolidate similar remaining functionality
function consolidatedFunction(params) {
  // Combine remaining similar logic into cleaner implementation
  return unifiedApproach(params);
}

Code Quality Improvements

• Simplify conditional logic when removing feature flags
• Consolidate similar functions that were previously separated
• Reduce prop drilling by removing unnecessary prop passing
• Improve type safety by removing optional types that are no longer needed

Success Metrics

A successful code removal should result in:

• ✅ Zero console errors and clean application startup
• ✅ All existing functionality preserved and working normally
• ✅ Cleaner, more maintainable codebase with no dead code
• ✅ Improved bundle size or performance (if applicable)
• ✅ Updated documentation reflecting current functionality
• ✅ No orphaned files or references in the codebase

Quick Reference Checklist

Before Starting Removal:

• Identify all files that reference the code to be removed
• Map out all dependencies and related functionality
• Plan removal order (UI → State → Logic → Data → Cleanup)

During Removal:

• Remove code incrementally, testing after each major step
• Preserve all working functionality not related to removed feature
• Fix any TypeScript or compilation errors immediately
• Clean up imports and exports as you go

After Removal:

• Verify application loads and functions normally
• Update all relevant documentation
• Update project tracking and issue management
• Remove any orphaned files or unused dependencies

This systematic approach ensures safe removal of unwanted code while maintaining application stability and code quality.