🎯

refactoring

🎯Skill

from cosmix/claude-loom

VibeIndex|
What it does

Systematically restructures code to enhance readability, maintainability, and performance while preserving its original behavior.

πŸ“¦

Part of

cosmix/claude-loom(12 items)

refactoring

Installation

Install ScriptRun install script
curl -fsSL https://raw.githubusercontent.com/cosmix/loom/main/install.sh | bash
git cloneClone repository
git clone https://github.com/cosmix/loom.git
Install ScriptRun install script
bash install.sh
πŸ“– Extracted from docs: cosmix/claude-loom
3Installs
-
AddedFeb 4, 2026

Skill Details

SKILL.md

|

Overview

# Refactoring

Overview

This skill focuses on improving code quality through systematic refactoring techniques. It identifies code smells and applies proven refactoring patterns to enhance maintainability while preserving functionality.

Use this skill when the user requests:

  • Code restructuring or cleanup
  • Reducing technical debt
  • Improving code organization
  • Applying design patterns
  • Breaking up large files or functions
  • Removing duplication
  • Modernizing legacy code
  • Improving testability

Scope Selection

When to use this skill:

  • Local refactoring (single module/file)
  • Pattern application (extract method, introduce interface)
  • Test refactoring and test suite improvements
  • Data pipeline restructuring
  • Safe refactoring with test coverage

When to escalate to senior-software-engineer:

  • Architectural changes affecting multiple modules
  • API redesign requiring migration paths
  • Cross-cutting refactoring with unclear scope
  • Performance optimization requiring profiling
  • Infrastructure refactoring (use infrastructure-related skills like /terraform, /kubernetes)
  • Security-sensitive refactoring (use /security-audit and /threat-model skills)

Instructions

1. Identify Refactoring Opportunities

Code Smells to Search For:

  • Long methods (>50 lines) or large classes (>300 lines)
  • Duplicated code blocks
  • High cyclomatic complexity
  • Magic numbers and string literals
  • Deep nesting (>3 levels)
  • Feature envy (method using data from another class)
  • Shotgun surgery (one change requires many edits)
  • Data clumps (same group of parameters)
  • Primitive obsession (using primitives instead of objects)

Use Grep/Glob to find patterns:

```bash

# Find long functions (rough heuristic)

rg "^(\s*)(def|function|fn|func)\s+\w+" --after-context=60

# Find duplicated code

rg --multiline "pattern.\n.pattern"

# Find magic numbers

rg "\b\d{2,}\b" --type=py --type=js --type=rs

```

2. Plan the Refactoring

Before starting:

  1. Verify test coverage - Run tests to establish baseline
  2. List all changes - Document sequence of refactorings
  3. Identify dependencies - What code depends on what you're changing?
  4. Plan rollback points - Where can you safely commit?
  5. Check for impact - Grep for references to functions/classes being changed

Red flags that require escalation:

  • No test coverage exists
  • Changes affect public APIs with external consumers
  • Unclear ownership or multiple teams involved
  • Performance-critical hot paths

3. Apply Refactoring Patterns

#### Code Organization Patterns

Extract Method/Function:

  • Break down long functions into smaller, focused ones
  • Each function should do one thing
  • Improves readability and testability

Extract Class:

  • Split large classes with multiple responsibilities
  • Follow Single Responsibility Principle
  • Improves cohesion and reduces coupling

Move Method/Field:

  • Relocate methods to classes that use their data
  • Reduces feature envy
  • Improves encapsulation

Inline Method/Variable:

  • Remove unnecessary indirection
  • Simplify overly abstracted code
  • Use when abstraction doesn't add value

Rename:

  • Improve naming clarity
  • Use domain language
  • Make intent explicit

#### Structural Patterns

Replace Conditional with Polymorphism:

  • Replace type switches with subclass methods
  • Enables Open/Closed Principle
  • Improves extensibility

Introduce Parameter Object:

  • Group related parameters into objects
  • Reduces parameter lists
  • Makes data relationships explicit

Replace Magic Numbers with Constants:

  • Define named constants for literals
  • Improves readability and maintainability
  • Centralizes configuration

Decompose Conditional:

  • Extract complex conditions into named functions
  • Replace nested ifs with guard clauses
  • Improves readability

#### Test Refactoring Patterns

Extract Test Fixture:

  • Move common setup into fixture/factory
  • Reduces duplication in test files
  • Improves test maintainability

Introduce Test Data Builder:

  • Replace complex object construction with builders
  • Makes test intent clearer
  • Simplifies test setup

Replace Assertion Roulette:

  • Use descriptive assertion messages
  • One logical assertion per test
  • Clear failure messages

Extract Test Helper:

  • Move repeated test logic into helpers
  • Keep tests focused on behavior
  • Improves test readability

#### Data Pipeline Patterns

Extract Transformation:

  • Isolate data transformation logic
  • Make transformations composable
  • Improves testability

Introduce Pipeline Interface:

  • Define standard input/output contracts
  • Enable stage composition
  • Simplifies testing and debugging

Replace Inline Processing with Stages:

  • Break monolithic processing into stages
  • Each stage has single responsibility
  • Enables parallelization and monitoring

4. Safe Refactoring Workflow

For each refactoring step:

  1. Make the change - One refactoring at a time
  2. Run tests - Verify behavior preserved
  3. Commit - Create checkpoint with clear message
  4. Repeat - Move to next refactoring

If tests fail:

  • Revert immediately (git checkout)
  • Analyze failure - is it a test issue or behavior change?
  • Fix or adjust approach

Commit message format:

```text

refactor: extract calculate_discount from process_order

Improves testability by isolating discount logic.

No behavior change.

```

5. Verify Changes

Verification checklist:

  • All tests pass (existing + any new tests)
  • No regressions in functionality
  • Performance hasn't degraded (for hot paths)
  • Code coverage maintained or improved
  • Linting passes
  • Build succeeds

For large refactorings:

  • Run additional smoke tests
  • Check memory usage (if applicable)
  • Review error handling preservation

Best Practices

  1. Small Steps: Make incremental changes, not big bang rewrites
  2. Test First: Ensure tests exist before refactoring - write them if missing
  3. One Thing at a Time: Focus on single refactoring per commit
  4. Preserve Behavior: External behavior must remain unchanged
  5. Keep It Working: Code should pass tests after each step
  6. Document Intent: Explain why refactoring was needed in commits
  7. Refactor Tests Too: Keep tests clean and maintainable
  8. Use Type Safety: Leverage type systems to catch errors early
  9. Measure Don't Guess: Profile before optimizing performance
  10. Know When to Stop: Don't over-engineer or add unnecessary abstraction

Common Patterns with Examples

Pattern 1: Extract Method

```python

# Before: Long method with multiple responsibilities

def process_order(order):

# Validate order

if not order.items:

raise ValueError("Empty order")

if order.total < 0:

raise ValueError("Invalid total")

# Calculate discount

discount = 0

if order.customer.is_premium:

discount = order.total * 0.1

if order.total > 1000:

discount += order.total * 0.05

# Apply discount and save

order.final_total = order.total - discount

order.save()

# After: Extracted methods with single responsibility

def process_order(order):

validate_order(order)

discount = calculate_discount(order)

finalize_order(order, discount)

def validate_order(order):

if not order.items:

raise ValueError("Empty order")

if order.total < 0:

raise ValueError("Invalid total")

def calculate_discount(order) -> float:

discount = 0

if order.customer.is_premium:

discount = order.total * 0.1

if order.total > 1000:

discount += order.total * 0.05

return discount

def finalize_order(order, discount: float):

order.final_total = order.total - discount

order.save()

```

Pattern 2: Replace Magic Numbers with Constants

```javascript

// Before

if (response.status === 200) {

setTimeout(retry, 3000);

if (attempts > 5) {

throw new Error("Max retries exceeded");

}

}

// After

const HTTP_OK = 200;

const RETRY_DELAY_MS = 3000;

const MAX_RETRY_ATTEMPTS = 5;

if (response.status === HTTP_OK) {

setTimeout(retry, RETRY_DELAY_MS);

if (attempts > MAX_RETRY_ATTEMPTS) {

throw new Error("Max retries exceeded");

}

}

```

Pattern 3: Replace Nested Conditionals with Guard Clauses

```python

# Before

def get_payment_amount(employee):

if employee.is_active:

if employee.is_full_time:

if employee.tenure > 5:

return employee.salary * 1.1

else:

return employee.salary

else:

return employee.hourly_rate * employee.hours

else:

return 0

# After

def get_payment_amount(employee):

if not employee.is_active:

return 0

if not employee.is_full_time:

return employee.hourly_rate * employee.hours

if employee.tenure > 5:

return employee.salary * 1.1

return employee.salary

```

Pattern 4: Introduce Parameter Object

```typescript

// Before

function createUser(

firstName: string,

lastName: string,

email: string,

phone: string,

street: string,

city: string,

state: string,

zip: string

) {

// ...

}

// After

interface UserDetails {

name: PersonName;

contact: ContactInfo;

address: Address;

}

interface PersonName {

first: string;

last: string;

}

interface ContactInfo {

email: string;

phone: string;

}

interface Address {

street: string;

city: string;

state: string;

zip: string;

}

function createUser(details: UserDetails) {

// ...

}

```

Pattern 5: Replace Type Code with Polymorphism

```rust

// Before

enum ShapeType { Circle, Rectangle, Triangle }

struct Shape {

shape_type: ShapeType,

radius: f64,

width: f64,

height: f64,

base: f64,

}

impl Shape {

fn area(&self) -> f64 {

match self.shape_type {

ShapeType::Circle => 3.14159 self.radius self.radius,

ShapeType::Rectangle => self.width * self.height,

ShapeType::Triangle => 0.5 self.base self.height,

}

}

}

// After

trait Shape {

fn area(&self) -> f64;

}

struct Circle { radius: f64 }

struct Rectangle { width: f64, height: f64 }

struct Triangle { base: f64, height: f64 }

impl Shape for Circle {

fn area(&self) -> f64 {

3.14159 self.radius self.radius

}

}

impl Shape for Rectangle {

fn area(&self) -> f64 {

self.width * self.height

}

}

impl Shape for Triangle {

fn area(&self) -> f64 {

0.5 self.base self.height

}

}

```

Pattern 6: Extract Data Pipeline Stage

```python

# Before: Monolithic processing

def process_data(raw_data):

# Validate

if not raw_data:

raise ValueError("Empty data")

# Clean

cleaned = []

for item in raw_data:

if item.get('status') == 'valid':

cleaned.append(item)

# Transform

transformed = []

for item in cleaned:

transformed.append({

'id': item['id'],

'value': item['raw_value'] * 100,

'timestamp': item['ts']

})

# Aggregate

total = sum(item['value'] for item in transformed)

return {'items': transformed, 'total': total}

# After: Pipeline with composable stages

def validate_input(raw_data):

if not raw_data:

raise ValueError("Empty data")

return raw_data

def filter_valid(data):

return [item for item in data if item.get('status') == 'valid']

def transform_items(data):

return [

{

'id': item['id'],

'value': item['raw_value'] * 100,

'timestamp': item['ts']

}

for item in data

]

def aggregate_results(transformed):

total = sum(item['value'] for item in transformed)

return {'items': transformed, 'total': total}

def process_data(raw_data):

return (raw_data

|> validate_input

|> filter_valid

|> transform_items

|> aggregate_results)

```

Pattern 7: Simplify Test with Builder

```go

// Before

func TestUserRegistration(t *testing.T) {

user := &User{

FirstName: "John",

LastName: "Doe",

Email: "john@example.com",

Phone: "555-0100",

Address: Address{

Street: "123 Main St",

City: "Springfield",

State: "IL",

Zip: "62701",

},

Preferences: Preferences{

NewsletterEnabled: true,

Theme: "dark",

},

CreatedAt: time.Now(),

}

err := RegisterUser(user)

assert.NoError(t, err)

}

// After

func TestUserRegistration(t *testing.T) {

user := NewUserBuilder().

WithName("John", "Doe").

WithEmail("john@example.com").

Build()

err := RegisterUser(user)

assert.NoError(t, err)

}

// Test builder focuses on what matters for each test

func TestUserWithNewsletter(t *testing.T) {

user := NewUserBuilder().WithNewsletter(true).Build()

// ...

}

```

When to Stop Refactoring

Stop if:

  • Tests start failing unexpectedly
  • Scope is expanding beyond initial plan
  • Unsure about architectural implications
  • Performance concerns arise
  • Security implications unclear

In these cases:

  • Commit current progress
  • Document remaining work
  • Escalate to senior-software-engineer or relevant specialist

More from this repository10

🎯
event-driven🎯Skill

Enables scalable, loosely-coupled systems by implementing event-driven architectures with message queues, pub/sub patterns, and distributed transaction management across various messaging platforms.

🎯
data-validation🎯Skill

Validates and sanitizes data across various formats and use cases, ensuring data integrity and security.

🎯
auth🎯Skill

Implements robust authentication and authorization patterns including OAuth2, JWT, MFA, access control, and identity management.

🎯
background-jobs🎯Skill

Manages asynchronous task processing with robust job queues, scheduling, worker pools, and advanced retry strategies across various frameworks.

🎯
testing🎯Skill

Comprehensively tests software across domains, implementing unit, integration, and end-to-end tests with TDD/BDD workflows and robust test architecture.

🎯
logging-observability🎯Skill

Enables comprehensive logging and observability by providing structured logging, distributed tracing, metrics collection, and centralized log management patterns.

🎯
feature-flags🎯Skill

Enables runtime feature control through configurable flags for gradual rollouts, A/B testing, user targeting, and dynamic system configuration.

🎯
grafana🎯Skill

Designs and configures Grafana dashboards, panels, and visualizations for observability using LGTM stack technologies like Loki, Tempo, and Mimir.

🎯
ci-cd🎯Skill

Designs and implements robust CI/CD pipelines with automated testing, security scanning, and deployment strategies across multiple platforms and tools.

🎯
prometheus🎯Skill

Configures and manages Prometheus monitoring, enabling metrics collection, PromQL querying, alerting rules, and service discovery for cloud-native observability.