refactoring-workflow_skill

Overview

This skill provides a complete, repeatable refactoring workflow for Rails projects with tracking, validation, and cross-layer checklists. It integrates with beads for task comments and status updates and ensures no lingering references to old names remain. Use it to coordinate multi-file renames, attribute changes, table migrations, and namespace moves reliably.

How this skill works

You start by recording the refactor intent, which captures old/new names, type, and an auto-detected list of affected files. As files are updated, progress comments are posted to beads and a running count of remaining references is shown. A validation step scans Ruby and ERB sources (and can be extended) to fail the task if any old tokens remain, with an option to mark the task blocked in beads.

When to use it

• Renaming a class, model, controller, or namespace across the codebase
• Renaming attributes or table names that require coordinated migrations and code changes
• Refactoring front-end Stimulus controllers or JavaScript identifiers tied to Rails views
• When you need an audit trail and task tracking for a multi-step refactor
• Before closing a refactor task to guarantee no old references remain

Best practices

• Record the refactor before making changes to capture scope and affected files
• Update files incrementally and call progress updates to keep the task audit accurate
• Run validation after each phase and before closing the task to catch missed references
• Maintain a .refactorignore for intentional legacy references that should not be updated
• Include cross-layer checklist items (views, routes, JS, I18n, migrations) in your plan

Example use cases

• Class rename: Payment → Transaction with model, controller, views, specs and JS updates
• Attribute rename: user_id → account_id including migration, strong params, and tests
• Table rename: payments → transactions with migration, schema verification, and raw SQL fixes
• Namespace move: Services::Payment → Billing::Transaction with file moves and autoload checks
• Stimulus refactor: payment_controller → transaction_controller updating data-controller attributes