refactoring-workflow-optimization

# Refactoring Workflow Optimization ## Overview Systematic approach to code refactoring with pre-analysis, batch planning, and validation checkpoints. Reduces refactoring time and improves first-attempt success rate. **Problem**: Refactoring tasks show 20+ individual edits when batch operations would be more efficient, TypeScript errors discovered after incomplete refactoring passes, agents miss local constant declarations that shadow class-level constants. **Solution**: Pre-analysis phase to find ALL occurrences, categorize by type, create refactoring plan with logical batches, validate after each batch. **Impact**: Reduce refactoring time by 60-70%, improve first-attempt success rate. ## Pre-Analysis Phase ### Step 1: Find ALL Occurrences **Use grep to find ALL occurrences of the pattern (not just first few):** ```typescript // ❌ INEFFICIENT: Only finding first few occurrences grep('TILE_SIZE', 'src/**/*.ts', { head_limit: 10 }); // ✅ EFFICIENT: Find ALL occurrences grep('TILE_SIZE', 'src/**/*.ts'); // No head_limit - get complete picture ``` ### Step 2: Categorize Occurrences **Categorize occurrences by type and location:** ```typescript // Categorize findings const occurrences = { declarations: [ { file: 'GameScene.ts', line: 15, type: 'class constant' }, { file: 'GameScene.ts', line: 45, type: 'local constant' }, ], usages: [ { file: 'GameScene.ts', line: 100, context: 'method call' }, { file: 'MainMenu.ts', line: 50, context: 'property access' }, ], testCode: [ { file: 'GameScene.test.ts', line: 20, context: 'test setup' }, ], comments: [ { file: 'GameScene.ts', line: 12, context: 'inline comment' }, ], }; ``` ### Step 3: Identify Shadowing Issues **Identify local constants that shadow class-level constants:** ```typescript // Example shadowing issue class GameScene { private static readonly TILE_SIZE = 32; // Class constant someMethod() { const TILE_SIZE = 16; // Local constant shadows class constant // This local declaration needs special handling } } // Identify shadowing const shadowingIssues = occurrences.declarations.filter( occ => occ.type === 'local constant' && hasClassConstant(occ.file, 'TILE_SIZE') ); ``` ### Step 4: Create Refactoring Plan **Create refactoring plan with logical edit batches:** ```typescript // Refactoring plan with logical batches const refactoringPlan = { batch1: { name: 'Class constant declarations', files: ['GameScene.ts'], edits: [ { line: 15, change: 'Replace class constant TILE_SIZE with TILE_WIDTH' }, ], validation: 'TypeScript check after batch', }, batch2: { name: 'Local constant declarations', files: ['GameScene.ts'], edits: [ { line: 45, change: 'Replace local constant TILE_SIZE with TILE_WIDTH' }, ], validation: 'TypeScript check after batch', }, batch3: { name: 'Usage sites', files: ['GameScene.ts', 'MainMenu.ts'], edits: [ { file: 'GameScene.ts', line: 100, change: 'Update usage' }, { file: 'MainMenu.ts', line: 50, change: 'Update usage' }, ], validation: 'TypeScript check after batch', }, }; ``` ## Batch Strategy ### Pattern 1: Group Related Edits **Group related edits (e.g., all TILE_SIZE declarations in one batch):** ```typescript // ✅ EFFICIENT: Batch all declarations together const declarations = [ { file: 'GameScene.ts', line: 15 }, { file: 'GameScene.ts', line: 45 }, { file: 'MainMenu.ts', line: 20 }, ]; // Batch edit all declarations for (const decl of declarations) { search_replace(decl.file, 'TILE_SIZE', 'TILE_WIDTH', { // Context around line }); } // Then validate once after batch run_terminal_cmd('npx tsc --noEmit'); ``` ### Pattern 2: Use Multi-Edit Operations **Use multi-edit operations when supported by tools:** ```typescript // ✅ EFFICIENT: Multi-edit operation search_replace('GameScene.ts', [ { old: 'TILE_SIZE', new: 'TILE_WIDTH', line: 15 }, { old: 'TILE_SIZE', new: 'TILE_WIDTH', line: 45 }, { old: 'TILE_SIZE', new: 'TILE_WIDTH', line: 100 }, ]); ``` ### Pattern 3: Leverage file-edit-batching Skill **Coordinate with file-edit-batching skill for effective batching:** ```typescript // Use file-edit-batching patterns // 1. Read all related files first const files = await Promise.all([ read_file('GameScene.ts'), read_file('MainMenu.ts'), ]); // 2. Identify all changes needed const changes = analyzeFiles(files); // 3. Batch independent changes batchIndependentChanges(changes); // 4. Keep dependent changes separate handleDependentChanges(changes); ``` ## Validation Checkpoints ### Pattern 1: Validate After Logical Batches **Run TypeScript check after each logical batch (not after every single edit):** ```typescript // ✅ CORRECT: Validate after logical batch // Batch 1: All declarations editDeclarations(); run_terminal_cmd('npx tsc --noEmit'); // Validate batch 1 // Batch 2: All usages editUsages(); run_terminal_cmd('npx tsc --noEmit'); // Validate batch 2 // ❌ WRONG: Validate after every edit editDeclaration1(); run_terminal_cmd('npx tsc --noEmit'); editDeclaration2(); run_terminal_cmd('npx tsc --noEmit'); ``` ### Pattern 2: Validate Before Testing **Always validate before starting browser testing phase:** ```typescript // Complete all refactoring batches editDeclarations(); editUsages(); editTestCode(); // Validate before testing run_terminal_cmd('npx tsc --noEmit'); if (hasErrors) { fixErrors(); run_terminal_cmd('npx tsc --noEmit'); } // Only then proceed to browser testing startBrowserTesting(); ``` ### Pattern 3: Re-validate After All Changes **Re-validate after all changes complete:** ```typescript // All refactoring complete completeAllRefactoring(); // Final validation run_terminal_cmd('npx tsc --noEmit'); run_terminal_cmd('npm run build'); // If applicable // Document completion updateProgressTxt('Refactoring complete, all validations pass'); ``` ## Documentation Patterns ### Pattern 1: Document Refactoring Patterns **Document refactoring patterns in progress.txt:** ```markdown ## Refactoring: TILE_SIZE → TILE_WIDTH ### Pre-Analysis - Found 15 occurrences total - 3 declarations (1 class constant, 2 local constants) - 10 usages - 2 test code references ### Shadowing Issues - GameScene.ts:45 - Local constant shadows class constant - Handled by replacing local constant first, then class constant ### Batches 1. **Batch 1**: Local constant declarations (2 edits) - Validation: ✅ TypeScript passes 2. **Batch 2**: Class constant declaration (1 edit) - Validation: ✅ TypeScript passes 3. **Batch 3**: Usage sites (10 edits) - Validation: ✅ TypeScript passes 4. **Batch 4**: Test code (2 edits) - Validation: ✅ TypeScript passes ### Learnings - Local constants can shadow class constants - Need to handle shadowing before class constant changes - Batching by type (declarations → usages → tests) works well ``` ### Pattern 2: Record Shadowing Learnings **Record learnings about shadowing and scope issues:** ```markdown ## Shadowing Detection Learnings ### Pattern Local constants can shadow class-level constants: ```typescript class GameScene { private static readonly TILE_SIZE = 32; // Class constant method() { const TILE_SIZE = 16; // Shadows class constant } } ``` ### Strategy 1. Identify shadowing during pre-analysis 2. Replace local constants first 3. Then replace class constants 4. Finally update usages ### Tools - Use grep to find all declarations - Check scope (local vs class) for each declaration - Categorize by scope before batching ``` ## Complete Workflow Example ### Example: Refactoring TILE_SIZE to TILE_WIDTH ```typescript // Step 1: Pre-Analysis const allOccurrences = grep('TILE_SIZE', 'src/**/*.ts'); const categorized = categorizeOccurrences(allOccurrences); const shadowingIssues = identifyShadowing(categorized); // Step 2: Create Plan const plan = createRefactoringPlan(categorized, shadowingIssues); // Step 3: Execute Batch 1 - Local Constants for (const edit of plan.batch1.localConstants) { search_replace(edit.file, edit.old, edit.new); } run_terminal_cmd('npx tsc --noEmit'); // Validate // Step 4: Execute Batch 2 - Class Constants for (const edit of plan.batch2.classConstants) { search_replace(edit.file, edit.old, edit.new); } run_terminal_cmd('npx tsc --noEmit'); // Validate // Step 5: Execute Batch 3 - Usages for (const edit of plan.batch3.usages) { search_replace(edit.file, edit.old, edit.new); } run_terminal_cmd('npx tsc --noEmit'); // Validate // Step 6: Execute Batch 4 - Test Code for (const edit of plan.batch4.testCode) { search_replace(edit.file, edit.old, edit.new); } run_terminal_cmd('npx tsc --noEmit'); // Validate // Step 7: Final Validation run_terminal_cmd('npx tsc --noEmit'); updateProgressTxt('Refactoring complete'); ``` ## Best Practices 1. **Find ALL occurrences**: Use grep without head_limit 2. **Categorize by type**: Declarations, usages, test code, comments 3. **Identify shadowing**: Check local vs class constants 4. **Create plan**: Logical batches before executing 5. **Batch related edits**: Group by type and location 6. **Validate after batches**: TypeScript check after logical batches 7. **Document patterns**: Record in progress.txt 8. **Learn from shadowing**: Document scope issues ## Common Pitfalls ### Pitfall 1: Incomplete Analysis **Problem**: Only finding first few occurrences **Solution**: Find ALL occurrences before planning ```typescript // ❌ WRONG: Limited search grep('TILE_SIZE', 'src/**/*.ts', { head_limit: 10 }); // ✅ CORRECT: Complete search grep('TILE_SIZE', 'src/**/*.ts'); ``` ### Pitfall 2: Missing Shadowing **Problem**: Missing local constants that shadow class constants **Solution**: Check scope for each declaration ```typescript // ❌ WRONG: Not checking scope const declarations = findAllDeclarations('TILE_SIZE'); // ✅ CORRECT: Check scope const declarations = findAllDeclarations('TILE_SIZE'); const shadowing = declarations.filter(d => isLocalConstant(d) && hasClassConstant(d)); ``` ### Pitfall 3: Validating After Every Edit **Problem**: Running TypeScript check after every single edit **Solution**: Validate after logical batches ```typescript // ❌ WRONG: Validate after every edit edit1(); run_terminal_cmd('npx tsc --noEmit'); edit2(); run_terminal_cmd('npx tsc --noEmit'); // ✅ CORRECT: Validate after batch edit1(); edit2(); edit3(); run_terminal_cmd('npx tsc --noEmit'); // Validate batch ``` ## Integration with Other Skills - **`file-edit-batching`**: Uses batching patterns for refactoring edits - **`file-operation-optimization`**: Uses file caching during analysis - **`timeout-prevention-operation-batching`**: Uses time tracking during refactoring ## Related Skills - `file-edit-batching` - File editing batching strategies - `file-operation-optimization` - File reading and caching - `timeout-prevention-operation-batching` - Time tracking patterns ## Remember 1. **Pre-analyze**: Find ALL occurrences before planning 2. **Categorize**: Group by type (declarations, usages, tests) 3. **Identify shadowing**: Check local vs class constants 4. **Plan batches**: Create logical edit batches 5. **Validate after batches**: TypeScript check after logical batches 6. **Document**: Record patterns in progress.txt 7. **Learn**: Document shadowing and scope issues