Paiml Paiml MCP Agent Toolkit Pmat Refactor

PMAT Automated Refactoring Skill

You are an expert at identifying refactoring opportunities and applying systematic code improvements using PMAT (Pragmatic AI Labs MCP Agent Toolkit).

When to Activate

This skill should automatically activate when:

1. User mentions "refactor", "optimize", "improve", or "simplify" code
2. Complexity analysis reveals functions with cyclomatic complexity > 10
3. User requests code modernization or technical debt reduction
4. Preparing code for new features (pre-refactoring)
5. Code review reveals maintainability concerns

Core Refactoring Workflow

Step 1: Baseline Analysis

Before any refactoring, establish baseline metrics:

# Analyze current complexity
pmat analyze complexity --path <target_file_or_directory> --output baseline_complexity.json

# Analyze quality metrics
pmat analyze quality --path <target_file_or_directory> --output baseline_quality.json

# Identify dead code
pmat analyze dead-code --path <target_file_or_directory> --output dead_code.json

Step 2: Identify Refactoring Targets

Prioritize based on:

• Cyclomatic Complexity > 10: High risk, needs simplification
• Cognitive Complexity > 15: High mental load
• Maintainability Index < 50: Difficult to maintain
• Code Duplication > 5%: Extract common patterns
• Dead Code: Remove unused functions/imports

Step 3: Apply Refactoring Patterns

Use industry-standard refactoring patterns (Fowler, 1999):

Pattern 1: Extract Method

When: Function has cyclomatic complexity > 10 Goal: Break down complex function into smaller, testable units

# Analyze function complexity
pmat analyze complexity --path src/services/parser.rs --format detailed

# Identify extraction candidates (high complexity blocks)
# Manual extraction using Edit tool, guided by complexity hotspots

Pattern 2: Simplify Conditionals

When: Deeply nested if/else statements (nesting depth > 3) Goal: Reduce cognitive complexity using early returns, guard clauses

# Identify nesting depth issues
pmat analyze complexity --path src/handlers/request.rs --metrics cognitive

# Apply transformations:
# - Replace nested if with early returns
# - Extract condition logic into named functions
# - Use pattern matching where applicable

Pattern 3: Remove Dead Code

When: Unused functions, imports, or variables detected Goal: Reduce codebase size, improve maintainability

# Detect dead code
pmat analyze dead-code --path src/ --output dead_code_report.json

# Review and remove confirmed dead code
# Use Edit tool to safely remove unused code

Pattern 4: Extract Class/Module

When: Single file exceeds 500 LOC or handles multiple responsibilities Goal: Improve modularity, single responsibility principle

# Analyze file size and responsibilities
pmat context --path src/large_module.py --output module_analysis.md

# Identify cohesive responsibilities
# Create new modules/classes
# Migrate related functions

Pattern 5: Reduce Duplication

When: Code duplication > 5% detected Goal: Extract common patterns, improve DRY principle

# Detect code duplication
pmat analyze duplication --path src/ --threshold 5 --output duplication.json

# Extract duplicated code into shared functions/modules

Step 4: Verify Refactoring Impact

After refactoring, measure improvements:

# Re-run complexity analysis
pmat analyze complexity --path <refactored_files> --output after_complexity.json

# Compare before/after metrics
pmat compare --baseline baseline_complexity.json --current after_complexity.json

# Ensure quality improved
pmat analyze quality --path <refactored_files> --output after_quality.json

Example Refactoring Workflows

Example 1: Simplify High-Complexity Function

Scenario: Function has cyclomatic complexity of 18

# Step 1: Analyze current state
pmat analyze complexity --path src/services/validator.rs

# Output (hypothetical):
# Function: validate_request
# Cyclomatic Complexity: 18 (HIGH)
# Cognitive Complexity: 24 (VERY HIGH)
# Lines: 150
# Nesting Depth: 4 (HIGH)

# Step 2: Identify refactoring opportunities
# - Extract validation logic into separate functions (lines 45-80)
# - Replace nested if statements with early returns (lines 90-120)
# - Extract complex condition into named function (line 105)

# Step 3: Apply refactorings using Edit tool
# [Use Edit tool to implement changes]

# Step 4: Verify improvement
pmat analyze complexity --path src/services/validator.rs

# Expected output:
# Function: validate_request (refactored)
# Cyclomatic Complexity: 6 (GOOD) ← Reduced from 18
# Cognitive Complexity: 8 (GOOD) ← Reduced from 24
# Lines: 80 ← Reduced from 150
# Nesting Depth: 2 (GOOD) ← Reduced from 4

# Improvement: 67% reduction in cyclomatic complexity

Example 2: Dead Code Cleanup

# Step 1: Identify dead code
pmat analyze dead-code --path src/

# Output:
# Found 15 unused functions:
# 1. src/utils/formatter.rs::legacy_format() - Last used in v1.2
# 2. src/helpers/validation.rs::old_validator() - Replaced by new_validator()
# 3. src/api/deprecated.rs::old_endpoint() - Deprecated in v2.0
# ...

# Step 2: Review and confirm removal safety
# Check git history, grep for usage, review tests

# Step 3: Remove dead code using Edit tool
# [Remove each unused function]

# Step 4: Measure impact
# - Binary size reduced by ~45KB
# - Maintainability index improved from 62 to 75
# - Reduced cognitive load for developers

Example 3: Extract Method Refactoring

# Step 1: Identify extraction candidate
pmat analyze complexity --path src/core/processor.rs --format detailed

# Output:
# Function: process_data
# Lines 100-180: Complexity 12 (candidate for extraction)
# Lines 200-250: Complexity 8 (candidate for extraction)

# Step 2: Extract complex sections into named methods
# Before:
# fn process_data(input: &str) -> Result<Data> {
#     // Lines 100-180: Data validation (complexity 12)
#     // Lines 200-250: Data transformation (complexity 8)
# }

# After (using Edit tool):
# fn process_data(input: &str) -> Result<Data> {
#     let validated = validate_input_data(input)?;
#     transform_validated_data(validated)
# }
#
# fn validate_input_data(input: &str) -> Result<Data> {
#     // Extracted validation logic
# }
#
# fn transform_validated_data(data: Data) -> Result<Data> {
#     // Extracted transformation logic
# }

# Step 3: Verify improvement
pmat analyze complexity --path src/core/processor.rs

# Results:
# - process_data: Complexity 3 (SIMPLE) ← Reduced from 20
# - validate_input_data: Complexity 6 (MODERATE)
# - transform_validated_data: Complexity 4 (SIMPLE)
# Total complexity: 13 (distributed across 3 testable functions)

Refactoring Decision Matrix

Use this matrix to prioritize refactoring efforts:

Generate this matrix using:

# Combine complexity + churn analysis
pmat analyze complexity --path src/ --output complexity.json
pmat analyze churn --path src/ --since "6 months ago" --output churn.json
pmat refactor-matrix --complexity complexity.json --churn churn.json

Refactoring Safety Checklist

Before applying refactorings:

1. ✅ Baseline metrics captured (complexity, quality, test coverage)
2. ✅ Tests exist and pass (run pmat test or project test suite)
3. ✅ Git commit created (safe rollback point)
4. ✅ Refactoring scope defined (one pattern at a time)
5. ✅ Impact understood (dependencies, callers identified)

After applying refactorings:

1. ✅ Tests still pass (regression check)
2. ✅ Complexity reduced (verify with pmat analyze complexity)
3. ✅ Functionality preserved (manual smoke test)
4. ✅ Code review requested (peer validation)

Integration with PMAT Quality Analysis

Refactoring should be guided by quality metrics:

# Generate comprehensive quality report
pmat analyze quality --path src/ --output quality_report.json

# Identify refactoring targets from quality report
# - Functions with maintainability index < 50
# - Files with technical debt > 10 hours
# - Modules with high coupling scores

# Apply targeted refactorings
# [Use patterns above]

# Verify quality improvement
pmat analyze quality --path src/ --output quality_after.json
pmat compare-quality --before quality_report.json --after quality_after.json

Scientific Foundation

PMAT refactoring implements peer-reviewed principles:

1. Fowler's Refactoring Catalog (1999)

   • Extract Method, Simplify Conditional, Remove Dead Code
   • Behavior-preserving transformations

2. McCabe's Cyclomatic Complexity (1976)

   • Threshold: 10 for well-structured code
   • Predictor of defect density

3. Cognitive Complexity (SonarSource, 2021)

   • Measures mental effort required to understand code
   • Guide for simplification priorities

4. Technical Debt Quadrant (Fowler, 2009)

   • Distinguish deliberate vs. inadvertent debt
   • Prioritize repayment strategies

Performance Optimization Tips

For large codebases:

1. Incremental Refactoring: Refactor one file/function at a time
2. Hot Path Priority: Focus on frequently changed files first
3. Complexity Threshold: Only refactor complexity > 10 (Pareto principle)
4. Measure Impact: Track time saved via maintainability improvements

Common Refactoring Patterns by Language

Rust

• Replace unwrap() with proper error handling (? operator)
• Extract complex match arms into functions
• Use impl Trait to simplify return types
• Apply lifetime elision rules

Python

• Extract nested functions for clarity
• Replace complex comprehensions with explicit loops
• Use dataclasses for data structures
• Apply type hints for better IDE support

JavaScript/TypeScript

• Extract arrow function logic into named functions
• Replace callback hell with async/await
• Use destructuring to simplify parameter passing
• Apply optional chaining (?.) to reduce null checks

Go

• Extract error handling into helper functions
• Simplify interface implementations
• Use defer for cleanup logic
• Apply table-driven tests

When NOT to Refactor

Avoid refactoring in these scenarios:

1. No Tests: Without tests, refactoring is unsafe (write tests first)
2. Unclear Requirements: Understand the domain before changing code
3. Hot Production Issues: Fix bugs first, refactor later
4. Large-Scale Changes: Break into smaller, incremental refactorings
5. Working Code: If complexity is low and code is stable, leave it

Limitations

• Semantic Preservation: PMAT suggests refactorings but cannot guarantee behavior preservation (test coverage required)
• Context Awareness: Automated suggestions may not account for domain-specific constraints
• Language-Specific Idioms: Some refactorings require language-specific expertise
• External Dependencies: Refactoring may require updating API contracts

Error Handling

If refactoring causes issues:

1. Rollback: git reset --hard HEAD (use the commit you created before refactoring)
2. Incremental Revert: Use Edit tool to undo specific changes
3. Test Isolation: Identify which refactoring broke tests
4. Consult Baseline: Compare against baseline metrics to identify regressions

Best Practices

1. One Pattern at a Time: Apply one refactoring pattern per commit
2. Test After Each Change: Verify tests pass after each refactoring
3. Commit Frequently: Create rollback points for safety
4. Measure Impact: Track complexity reduction and quality improvement
5. Document Rationale: Explain why refactoring was needed (commit messages, code comments)
6. Peer Review: Get feedback on refactoring approach before merging

Integration with Other PMAT Skills

Workflow Recommendation:

1. pmat-context: Understand codebase structure
2. pmat-quality: Identify quality issues
3. pmat-refactor: Apply systematic improvements ← This skill
4. pmat-tech-debt: Track debt repayment progress

Version Requirements

• Minimum: PMAT v2.170.0
• Recommended: Latest version for best refactoring suggestions
• Check version: pmat --version

Remember: Refactoring is about improving code structure WITHOUT changing behavior. Always start with tests, establish baselines, apply one pattern at a time, and verify improvements with data.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.