awannaphasch2016/refacter

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:

| 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

# 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

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

| 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

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