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

•Identify shadowing during pre-analysis
•Replace local constants first
•Then replace class constants
•Finally update usages

Tools

•Use grep to find all declarations
•Check scope (local vs class) for each declaration
•Categorize by scope before batching

code


## 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

•Find ALL occurrences: Use grep without head_limit
•Categorize by type: Declarations, usages, test code, comments
•Identify shadowing: Check local vs class constants
•Create plan: Logical batches before executing
•Batch related edits: Group by type and location
•Validate after batches: TypeScript check after logical batches
•Document patterns: Record in progress.txt
•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

•Pre-analyze: Find ALL occurrences before planning
•Categorize: Group by type (declarations, usages, tests)
•Identify shadowing: Check local vs class constants
•Plan batches: Create logical edit batches
•Validate after batches: TypeScript check after logical batches
•Document: Record patterns in progress.txt
•Learn: Document shadowing and scope issues