Refactor Plan Skill

Generate a structured, risk-assessed refactoring plan for a package or module.

When to Use

• Before starting a significant refactoring effort
• When code complexity exceeds maintainability thresholds
• When migrating between patterns or architectures
• When consolidating related functionality across packages

Analysis Steps

1. Current State Assessment

Read the target code and evaluate:

• Size: Line counts for files and functions. Flag functions > 50 lines.
• Complexity: Nesting depth, cyclomatic complexity, branching density.
• Coupling: External dependencies, tight coupling between modules.
• Cohesion: How well each module focuses on a single responsibility.
• Type safety: Usage of any, unknown, and proper type narrowing.
• Test coverage: Which public functions have corresponding tests.

2. Identify Improvement Opportunities

Common refactoring targets in Cacti:

• Extract interface: Create I-prefixed interfaces for dependency injection and testing.
• Consolidate duplicates: Merge identical logic across modules.
• Simplify conditionals: Replace nested if/else with early returns, guard clauses, or strategy pattern.
• Reduce coupling: Introduce dependency injection, event-driven patterns, or facade classes.
• Improve naming: Rename to follow Cacti conventions (I prefix, isI type guards).
• Barrel file cleanup: Ensure public-api.ts exports are accurate and minimal.
• Package boundary: Move code to the correct package to avoid circular dependencies.

3. Risk Assessment

For each proposed change, evaluate:

• Breaking changes: Will this change public API signatures?
• Downstream impact: Which packages depend on the changed code?
• Test coverage: Are there tests to catch regressions?
• Rollback difficulty: How easy is it to revert if something breaks?

4. Phase Planning

Break the refactoring into phases that:

• Each phase is independently mergeable
• Tests pass at the end of every phase
• Breaking changes are isolated and documented
• Higher-risk changes come later after confidence is built

Output Format

# Refactoring Plan: [Package/Module]

## Current State
- **Files**: [count] | **Functions**: [count] | **Lines**: [total]
- **Key concerns**: [summary of issues found]

## Proposed Changes

### Phase 1: [Safe, Non-Breaking Changes]
| # | Change | Files | Risk | Tests |
|---|--------|-------|------|-------|
| 1 | [description] | [files] | Low | [existing/needed] |

### Phase 2: [Structural Improvements]
| # | Change | Files | Risk | Tests |
|---|--------|-------|------|-------|
| 1 | [description] | [files] | Medium | [existing/needed] |

### Phase 3: [Higher-Risk Changes]
| # | Change | Files | Risk | Tests |
|---|--------|-------|------|-------|
| 1 | [description] | [files] | High | [existing/needed] |

## Dependency Map
[which packages are affected by each phase]

## Rollback Strategy
[how to revert each phase independently]