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

bash

# 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:

Code Churn	Complexity	Priority	Action
High	High	P0 - Critical	Refactor immediately
High	Low	P1 - Monitor	Add tests, watch for complexity
Low	High	P2 - Technical Debt	Refactor when touching code
Low	Low	P3 - Ignore	No action needed

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

bash

# 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

Metric	Good	Warning	Critical	Refactor Action
Cyclomatic Complexity	1-10	11-20	21+	Extract methods, simplify conditionals
Cognitive Complexity	1-15	16-25	26+	Reduce nesting, early returns
Lines of Code (LOC)	1-50	51-100	101+	Extract methods, split responsibilities
Function Parameters	1-4	5-6	7+	Introduce parameter object

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

bash

# 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

bash

# 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

Measure First, Refactor Second: Use metrics to identify what needs refactoring
Prioritize by Risk: Hotspots (high churn + high complexity) are highest priority
Incremental Refactoring: Small, testable changes
Test Coverage First: Add tests before refactoring risky code
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.

python

# ❌ 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:

Current	Problem	Refactor To	Benefit
CoV (Values)	Distributed transaction	Event-driven	No shared state
CoE (Execution)	Must call in order	Encapsulate order	Hide complexity
CoP (Position)	Positional params	Named params (CoN)	Self-documenting
CoM (Meaning)	Magic numbers	Named constants (CoN)	Clear intent

Three Properties of Connascence

Strength: How hard to refactor (dynamic > static)
Locality: How far apart (same file < different services)
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

Search AI Tools

refacter

Install this agent skill to your Project

SKILL.md

Refacter Skill

When to Use This Skill

Quick Refactoring Decision Tree

Loop Pattern: Branching Loop (Evaluate Refactoring Approaches)

Refactoring Workflow

Step 1: Profile Current State

Step 2: Prioritize Refactoring Targets

Step 3: Apply Refactoring Patterns

Step 4: Verify Improvement

Complexity Thresholds

Common Refactoring Scenarios

Scenario 1: Complex Conditional Logic

Scenario 2: Long Functions

Scenario 3: Frequent Changes + High Complexity

Scenario 4: Duplicated Code

Quick Reference

Run Complexity Analysis

Run Hotspot Analysis

Refactoring Principles

Core Principles

When NOT to Refactor

The "Rule of Three"

Connascence: Coupling with Precision

The Strength Hierarchy (Refactor UP this ladder)

Refactoring by Connascence Strength

Three Properties of Connascence

File Organization

Next Steps

References