Refactoring Workflow Skill

Systematic refactoring with tracking, validation, and completeness verification.

Quick Start

# 1. Record what you're refactoring
record_refactoring "Payment" "Transaction" "class_rename"

# 2. Update files, track progress
update_refactoring_progress "Payment" "app/models/transaction.rb"

# 3. Validate no old references remain
validate_refactoring "Payment" "Transaction"

1. Refactoring Log Functions

record_refactoring()

Start refactoring by recording what's being changed:

record_refactoring() {
  local old_name=$1
  local new_name=$2
  local refactor_type=$3  # class_rename, attribute_rename, method_rename, table_rename

  if [ -n "$TASK_ID" ] && command -v bd &> /dev/null; then
    bd comment $TASK_ID "🔄 Refactoring Log: $old_name → $new_name

**Type**: $refactor_type
**Started**: $(date -u +"%Y-%m-%d %H:%M:%S UTC")
**Status**: ⏳ In Progress

### Changes Planned

1. **$(echo $refactor_type | sed 's/_/ /g')**: \`$old_name\` → \`$new_name\`

### Affected Files (Auto-detected)

\`\`\`bash
# Ruby files referencing old name
$(rg --files-with-matches \"\\b$old_name\\b\" --type ruby 2>/dev/null | head -20 || echo "None detected")
\`\`\`

### Validation Checklist

- [ ] No references to \`$old_name\` in Ruby files
- [ ] No references in view templates
- [ ] No references in routes
- [ ] No references in specs
- [ ] No references in factories
- [ ] Migration files checked (if applicable)"
  fi
}

# Examples:
# record_refactoring "Payment" "Transaction" "class_rename"
# record_refactoring "user_id" "account_id" "attribute_rename"
# record_refactoring "payments" "transactions" "table_rename"

update_refactoring_progress()

Track progress as files are updated:

update_refactoring_progress() {
  local old_name=$1
  local file_updated=$2

  if [ -n "$TASK_ID" ] && command -v bd &> /dev/null; then
    bd comment $TASK_ID "✅ Refactoring Progress: Updated \`$file_updated\`

Old references to \`$old_name\` in this file have been updated.

Remaining files: $(rg --files-with-matches \"\\b$old_name\\b\" --type ruby 2>/dev/null | wc -l || echo "?")"
  fi
}

validate_refactoring()

Validate all references have been updated:

validate_refactoring() {
  local old_name=$1
  local new_name=$2

  echo "🔍 Validating refactoring: $old_name → $new_name"

  # Check for remaining references
  local remaining=$(rg --count "\\b$old_name\\b" --type ruby --type erb 2>/dev/null | wc -l)

  if [ "$remaining" -gt 0 ]; then
    echo "❌ Refactoring validation failed"
    echo "Found $remaining files still referencing '$old_name':"
    rg --files-with-matches "\\b$old_name\\b" --type ruby --type erb 2>/dev/null

    if [ -n "$TASK_ID" ] && command -v bd &> /dev/null; then
      bd update $TASK_ID --status blocked
    fi

    return 1
  else
    echo "✅ Refactoring validation passed"
    echo "All references to '$old_name' successfully updated."
    return 0
  fi
}

2. Complete Refactoring Workflow

Workflow Steps

Start: Record refactoring with record_refactoring()
Update: Update files incrementally, track with update_refactoring_progress()
Validate: Before phase completion, run validate_refactoring()
Fix: If validation fails, update remaining references
Re-validate: Run validation again until it passes
Complete: Only close task after validation passes

Example: Class Rename Workflow

# Phase starts: Renaming Payment to Transaction

# Step 1: Record refactoring
record_refactoring "Payment" "Transaction" "class_rename"

# Step 2: Update model file
mv app/models/payment.rb app/models/transaction.rb
# Update class name in file
sed -i 's/class Payment/class Transaction/g' app/models/transaction.rb
update_refactoring_progress "Payment" "app/models/transaction.rb"

# Step 3: Update associations in other models
# ... update files ...
update_refactoring_progress "Payment" "app/models/account.rb"

# Step 4: Update controller
mv app/controllers/payments_controller.rb app/controllers/transactions_controller.rb
# ... update class name and references ...
update_refactoring_progress "Payment" "app/controllers/transactions_controller.rb"

# Step 5: Update views, specs, factories, routes
# ... update all remaining files ...

# Step 6: Validate completeness
validate_refactoring "Payment" "Transaction"

if [ $? -eq 0 ]; then
  echo "✅ Refactoring complete"
else
  echo "❌ Refactoring incomplete, fix remaining references"
fi

3. Cross-Layer Impact Checklists

Class Rename Checklist

When renaming Payment → Transaction:

Ruby Layer:

Model class definition
Associations in other models (has_many :payments)
Controller class name
Controller instance variables (@payment)
Service class references
Job class references
Serializer references
String references (polymorphic: "Payment")

View Layer:

View template paths (app/views/payments/)
View helpers and form objects
Partials and layouts

Routes:

Route resources (resources :payments)
Named routes and path helpers

Tests:

Spec describe blocks
Factory definitions (:payment, :payments)
Fixtures (if used)

JavaScript/Frontend:

Stimulus controllers (payment_controller.js)
Stimulus class names (PaymentController)
data-controller attributes (data-controller="payment")
data-action attributes (data-action="payment#submit")
JavaScript imports and references
Event names (payment:updated)
Turbo frame IDs (#payment-form)
Importmap pins

I18n:

Locale keys (activerecord.models.payment)

Configuration:

Initializer references
Environment configs

Attribute Rename Checklist

When renaming user_id → account_id:

Database:

Migration (column rename)
Run migration: rails db:migrate
Verify in schema.rb

Model:

Attribute references
Validations
Associations (:foreign_key option)
Scopes and queries

Controller:

Strong params

Views:

Form fields
Display references

Tests:

Spec let statements
Factory attributes

API:

Serializer attributes
API documentation

JavaScript:

data-{controller}-{attr}-value attributes
Stimulus value definitions

I18n:

Attribute keys (activerecord.attributes.model.user_id)

Table Rename Checklist

When renaming payments → transactions:

JavaScript/Stimulus Refactoring Checklist

When renaming payment → transaction in frontend:

Namespace/Module Move Checklist

When moving Services::Payment → Billing::Transaction:

File path (app/services/payment.rb → app/billing/transaction.rb)
Module/namespace declaration
All references to the old namespace
Autoload paths (if custom)
Spec file path
Factory namespace
Route namespace (if applicable)

4. Intentional Legacy References

Create .refactorignore to exclude files from validation:

# .refactorignore - Files to exclude from refactoring validation

# Legacy compatibility layer
lib/legacy_api_adapter.rb

# Historical documentation
CHANGELOG.md
docs/migration_guide.md

# Rename migrations (reference old names by design)
db/migrate/*_rename_*.rb

# External API contracts (can't change)
app/serializers/api/v1/*_serializer.rb

5. Integration with Beads

Refactoring workflow integrates with beads for:

Task Tracking: Creates comments for start, progress, completion
Status Updates: Sets task to blocked if validation fails
Audit Trail: Full history of what was changed and when

# Set TASK_ID before starting refactoring
export TASK_ID="PROJ-123"

# All functions will automatically log to beads
record_refactoring "Payment" "Transaction" "class_rename"
update_refactoring_progress "Payment" "app/models/transaction.rb"
validate_refactoring "Payment" "Transaction"

6. Quick Reference

Function	Purpose	Example
`record_refactoring`	Start tracking	`record_refactoring "Old" "New" "class_rename"`
`update_refactoring_progress`	Track file update	`update_refactoring_progress "Old" "path/file.rb"`
`validate_refactoring`	Check completeness	`validate_refactoring "Old" "New"`

Refactor Type	Key Layers to Check
`class_rename`	Model, Controller, Views, Routes, Specs, JS
`attribute_rename`	Model, Controller params, Views, Specs, JS values
`table_rename`	Migration, Schema, Raw SQL
`method_rename`	All call sites, Specs
`namespace_move`	File paths, Autoloading, All references

Refactoring Workflow