refactoring-workflow-optimization

name	refactoring-workflow-optimization
description	Systematic approach to code refactoring with pre-analysis, batch planning, and validation checkpoints. Use when refactoring code to reduce refactoring time by 60-70% and improve first-attempt success rate.

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):

// ❌ 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:

// 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:

// 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:

// 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):

// ✅ 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:

// ✅ 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:

// 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):

// ✅ 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:

// 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:

// 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:

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

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

// ❌ 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

// ❌ 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

// ❌ 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