Refacter Skill

Tech Stack: Python 3.11+, radon (complexity analysis), git (code churn analysis)

Source: Extracted from CLAUDE.md global refactoring principles and industry best practices.

When to Use This Skill

Use the refactor skill when:

• •✓ User explicitly asks to refactor code
• •✓ Code complexity metrics exceed thresholds (cyclomatic > 10, cognitive > 15)
• •✓ Hotspot analysis reveals high-risk areas (high churn + high complexity)
• •✓ Adding new features to complex legacy code
• •✓ Before major refactoring to understand current state

DO NOT use this skill for:

• •✗ Simple formatting changes (use just format instead)
• •✗ Renaming variables (straightforward refactoring)
• •✗ One-off code improvements without analysis

Quick Refactoring Decision Tree

Is code complex/hard to understand?
├─ YES → Measure complexity (radon)
│   ├─ Cyclomatic > 10? → Extract methods, simplify conditionals
│   └─ Cognitive > 15? → Reduce nesting, early returns
│
└─ NO → Is code changing frequently (hotspot)?
    ├─ YES → Analyze code churn + complexity
    │   └─ High churn + high complexity? → Priority refactor target
    │
    └─ NO → Is code tightly coupled (connascence)?
        ├─ YES → Analyze connascence strength
        │   ├─ Dynamic connascence (CoE, CoV)? → Critical, refactor to static
        │   ├─ Strong static (CoP, CoM, CoA)? → Refactor to weaker forms
        │   └─ Weak static (CoN, CoT)? → Acceptable
        │
        └─ NO → Is code duplicated?
            ├─ YES → Extract common patterns
            └─ NO → Code is fine, no refactor needed

Loop Pattern: Branching Loop (Evaluate Refactoring Approaches)

Escalation Trigger:

• •Multiple refactoring approaches available
• •/compare needed to evaluate trade-offs
• •/impact assessment for each approach

Tools Used:

• •/compare - Compare refactoring strategies (extract method vs extract class vs redesign)
• •/impact - Assess blast radius of each approach (files affected, test changes, deployment risk)
• •/validate - Verify refactoring preserves behavior (run tests)
• •/reflect - Synthesize which approach worked best

Why This Works: Refactoring naturally involves branching—choosing between different improvement paths based on complexity analysis.

See Thinking Process Architecture - Feedback Loops for structural overview.

Refactoring Workflow

Step 1: Profile Current State

# Analyze code complexity
python .claude/skills/refacter/scripts/analyze_complexity.py src/

# Identify hotspots (high churn + high complexity)
python .claude/skills/refacter/scripts/analyze_hotspots.py src/

Step 2: Prioritize Refactoring Targets

Priority Matrix:

Step 3: Apply Refactoring Patterns

See REFACTORING-PATTERNS.md for specific techniques:

Complexity-Based:

• •Extract Method (reduce function length)
• •Extract Class (separate concerns)
• •Simplify Conditionals (reduce nesting)
• •Replace Magic Numbers (constants)
• •Introduce Parameter Object (reduce parameter count)

Connascence-Based:

• •CoP → CoN (positional parameters → named parameters)
• •CoM → CoN (magic numbers → named constants)
• •CoE → Encapsulation (execution order → hidden internally)
• •CoV → Event-Driven (shared values → eventual consistency)

Step 4: Verify Improvement

# Run complexity analysis again
python .claude/skills/refacter/scripts/analyze_complexity.py src/

# Ensure complexity decreased
# Run tests to ensure behavior unchanged
pytest tests/

Complexity Thresholds

Source: Based on industry standards (SonarQube, Code Climate, radon)

Common Refactoring Scenarios

Scenario 1: Complex Conditional Logic

Symptom: Deeply nested if/else, multiple conditions Metric: High cyclomatic complexity (> 10) Solution: See REFACTORING-PATTERNS.md#simplify-conditionals

Scenario 2: Long Functions

Symptom: Function > 50 lines, does many things Metric: High LOC, high cyclomatic complexity Solution: Extract Method pattern

Scenario 3: Frequent Changes + High Complexity

Symptom: File changed in 20+ commits, cyclomatic > 15 Metric: Hotspot analysis shows P0 priority Solution: Add tests first, then refactor incrementally

Scenario 4: Duplicated Code

Symptom: Same logic in multiple places Metric: No specific metric (manual detection) Solution: Extract common patterns, DRY principle

Quick Reference

Run Complexity Analysis

# Analyze specific directory
python .claude/skills/refacter/scripts/analyze_complexity.py src/agent/

# Analyze with thresholds
python .claude/skills/refacter/scripts/analyze_complexity.py src/ --max-cc 10 --max-cognitive 15

# Output to JSON for further processing
python .claude/skills/refacter/scripts/analyze_complexity.py src/ --json > complexity.json

Run Hotspot Analysis

# Analyze git hotspots (last 6 months)
python .claude/skills/refacter/scripts/analyze_hotspots.py src/

# Custom time range
python .claude/skills/refacter/scripts/analyze_hotspots.py src/ --since "3 months ago"

# Show top 10 hotspots
python .claude/skills/refacter/scripts/analyze_hotspots.py src/ --top 10

Refactoring Principles

From CLAUDE.md global instructions:

"when ask to refactor, use code complexity analysis, and hotspot analysis to profile codebase."

Core Principles

1. •Measure First, Refactor Second: Use metrics to identify what needs refactoring
2. •Prioritize by Risk: Hotspots (high churn + high complexity) are highest priority
3. •Incremental Refactoring: Small, testable changes
4. •Test Coverage First: Add tests before refactoring risky code
5. •Avoid Over-Engineering: Only refactor to thresholds, not perfection

When NOT to Refactor

• •❌ Code works and rarely changes (low churn, low complexity)
• •❌ No tests exist and risk is high (add tests first)
• •❌ Deadline pressure (tech debt ticket instead)
• •❌ Cosmetic changes without measurable benefit

The "Rule of Three"

Pattern: Only extract abstraction when you see the same pattern THREE times.

# ❌ BAD: Premature abstraction (seen once)
def process_single_case():
    return generic_abstraction(params)

# ✅ GOOD: Wait for third occurrence
# First time: Write inline
# Second time: Note similarity
# Third time: Extract pattern

Connascence: Coupling with Precision

Connascence = Two components are connascent if changing one requires changing the other.

The Strength Hierarchy (Refactor UP this ladder)

STATIC (Weakest - detectable at compile time)
├─ Connascence of Name (CoN)           ← WEAKEST (acceptable)
├─ Connascence of Type (CoT)           ← Weak (acceptable)
├─ Connascence of Meaning (CoM)        ← Medium (should improve)
├─ Connascence of Position (CoP)       ← Medium (should improve)
└─ Connascence of Algorithm (CoA)      ← Strong (document clearly)

DYNAMIC (Strongest - only runtime detection)
├─ Connascence of Execution (CoE)      ← Very Strong (refactor!)
├─ Connascence of Timing (CoT)         ← Very Strong (refactor!)
├─ Connascence of Values (CoV)         ← Strongest (critical!)
└─ Connascence of Identity (CoI)       ← Strongest (critical!)

Refactoring by Connascence Strength

Always refactor from stronger → weaker forms:

Three Properties of Connascence

1. •Strength: How hard to refactor (dynamic > static)
2. •Locality: How far apart (same file < different services)
3. •Degree: How many affected (2 components < 10 components)

Rule: As distance increases, use weaker forms

• •✅ OK: Dynamic connascence within a class
• •❌ BAD: Dynamic connascence across microservices

See REFACTORING-PATTERNS.md for connascence-based refactoring examples.

File Organization

.claude/skills/refacter/
├── SKILL.md                  # This file (entry point)
├── CODE-COMPLEXITY.md        # Complexity metrics guide
├── HOTSPOT-ANALYSIS.md       # Code churn + complexity
├── REFACTORING-PATTERNS.md   # Common refactoring techniques
└── scripts/
    ├── analyze_complexity.py # Complexity analysis tool
    └── analyze_hotspots.py   # Hotspot detection tool

Next Steps

• •For complexity metrics: See CODE-COMPLEXITY.md
• •For hotspot detection: See HOTSPOT-ANALYSIS.md
• •For refactoring techniques: See REFACTORING-PATTERNS.md
• •For code style: See docs/CODE_STYLE.md

References

• •Martin Fowler: Refactoring - Catalog of refactoring patterns
• •Fundamentals of Software Architecture - Connascence concepts
• •Code Climate: Cognitive Complexity
• •Your Code as a Crime Scene - Hotspot analysis origins
• •radon Documentation - Python complexity tool