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 :

• Migration (table rename)

• Run migration: rails db:migrate

• Verify in schema.rb

• Model table_name declaration (if explicit)

• Foreign key constraints

• Indexes

• Raw SQL queries

• Database views (if any)

JavaScript/Stimulus Refactoring Checklist

When renaming payment → transaction in frontend:

• Controller file rename (payment_controller.js → transaction_controller.js )

• Controller class name (PaymentController → TransactionController )

• data-controller attributes in views

• data-{controller}-target attributes

• data-action attributes

• JavaScript imports

• Event names and dispatching

• CSS class names that reference the controller

• Turbo frame IDs

• Importmap pins

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