SDD-Refactor: Safe Refactoring Skill

Overview

Skill(foundry:foundry-refactor) provides LSP-powered refactoring with safety checks. It uses findReferences to understand impact before making changes, performs batch edits, and verifies correctness.

Core capabilities:

• •Safe rename operations with complete reference updates
• •Extract function/method with reference updating
• •Move symbol across files with import fixups
• •Unused code cleanup based on zero-reference analysis

IMPORTANT: This skill uses Claude Code's built-in LSP tools for precise refactoring. If LSP returns no results for the target language, fall back to Grep-based patterns.

Skill Family

This skill integrates with the Spec-Driven Development workflow:

foundry-spec --> foundry-refactor (for planned refactoring tasks) --> foundry-implement --> foundry-review

Can also be used standalone for ad-hoc refactoring outside of specs.

When to Use This Skill

Use Skill(foundry:foundry-refactor) for:

• •Renaming classes, functions, methods, or variables across codebase
• •Extracting code into new functions/methods
• •Moving symbols between files/modules
• •Cleaning up unused code (dead code removal)
• •Any refactoring that affects multiple files

Do NOT use for:

• •Simple single-file edits (use Edit tool directly)
• •Creating new code from scratch (use foundry-spec + implement)
• •Deleting entire files (manual operation)
• •Formatting or style changes (use formatter tools)

Flow

[x?]=decision · (GATE)=user approval · →=sequence · ↻=loop · §=section ref

- **Entry** → Select type: Rename, Extract, Move, Cleanup → Validate target
  - [LSP available?] → `documentSymbol` → `goToDefinition`
  - [else] → Grep fallback
  - Impact analysis → `findReferences` → Assess risk: refs <10, <50, 50-100, >100 → (GATE: approve scope)
  - Execute → Operation path: rename, extract, move, cleanup
  - Verify → Structural LSP → References LSP → Tests via foundry-test
  - Document
    - [spec task?] → Journal entry
    - [else] → skip
  - **Exit**: Done

LSP Tools

This skill uses Claude Code's built-in LSP tools directly:

For spec integration, use foundry-mcp:

Core Workflow

Step 1: Identify Refactoring Target

Gather information about what to refactor:

1. •

   User provides:

   • •Symbol name (class, function, variable)
   • •File path containing the symbol
   • •Refactoring type (rename, extract, move, cleanup)
   • •New name or destination (if applicable)
2. •

   Validate target exists with LSP:

   code

   definition = goToDefinition(file="src/module.py", symbol="OldClassName", line=10)
   
   if definition found:
       Proceed to impact analysis
   else:
       Ask user to verify symbol name and location
   

3. •

   Fallback if LSP unavailable:

   code

   Use Grep to verify symbol exists:
   Grep(pattern="class OldClassName", path="src/")
   

Step 2: Impact Analysis (REQUIRED)

NEVER refactor without understanding impact first.

1. •Use findReferences to get all usages of the symbol
2. •Analyze: total count, unique files, reference types (import, call, annotation)
3. •Present impact report to user with risk assessment
4. •Get user approval before proceeding

CRITICAL: Read references/impact-analysis.md before refactoring. Contains required impact report format.

Step 3: Execute Refactoring

Execute the appropriate operation based on refactoring type:

See references/operations.md for detailed procedures for each operation type.

Step 4: Verify Correctness

After any refactoring:

1. •

   Structural verification (LSP):

   code

   documentSymbol(file="src/module.py")
   # Verify expected structure preserved
   

2. •

   Reference verification (LSP):

   code

   findReferences(file="src/module.py", symbol="NewName")
   # Verify all references resolve
   

3. •

   Run affected tests:

   code

   Skill(foundry:foundry-test) "Run tests for affected files"
   

Step 5: Document Changes

If refactoring is part of a spec task:

mcp__plugin_foundry_foundry-mcp__task action="complete" spec_id="{spec-id}" task_id="{task-id}" completion_notes="Renamed OldClassName to NewClassName across 12 files. All tests passing."

For significant refactors, add journal entry:

mcp__plugin_foundry_foundry-mcp__journal action="add" spec_id="{spec-id}" title="Refactoring: OldClassName -> NewClassName" content="Renamed class for clarity. 47 references updated across 12 files. No functional changes." entry_type="decision"

LSP Availability Check

Before using LSP-enhanced workflow, verify by calling documentSymbol on the target file. If it returns successfully, use LSP workflow. Otherwise, fall back to Grep-based workflow.

See references/lsp-check.md for fallback triggers and verification procedure.

Size Guidelines

Example Invocations

Rename class:

Skill(foundry:foundry-refactor) "Rename AuthService to AuthenticationService in src/auth/service.py"

Extract method:

Skill(foundry:foundry-refactor) "Extract lines 45-67 in src/handlers.py into new method validate_request"

Move function:

Skill(foundry:foundry-refactor) "Move helper_function from src/utils.py to src/helpers/common.py"

Dead code cleanup:

Skill(foundry:foundry-refactor) "Find and remove unused functions in src/legacy/"

Rename with spec context:

Skill(foundry:foundry-refactor) "Complete task-2-3: Rename UserDTO to UserResponse as specified"

Detailed Reference

For comprehensive documentation including:

• •Impact analysis → references/impact-analysis.md
• •Refactoring operations → references/operations.md
• •LSP availability check → references/lsp-check.md
• •Troubleshooting → references/troubleshooting.md