vm-refactor-planner

# VM Refactor Planner

## Overview

Converts code quality findings (from Code Optimization Agent) or architectural findings (from Architectural Review Agent) into a sequenced, commit-level refactor plan. Every step in the plan is a small, independently reversible change. The goal is to transform a list of problems into a safe, teachable sequence of incremental commits.

## When to Use

- After `docs/code-optimization/findings.json` or `docs/architectural-review/assessment.json` has been produced
- When the team agrees changes are needed but does not know what order to execute them safely
- When a PR review has identified a set of related issues that should be addressed together
- When a tech debt sprint needs to be planned as a concrete commit sequence

## When NOT to Use

- To generate the implementation code itself (this skill produces a plan, not code)
- For greenfield work where there is no existing code to refactor
- When findings have not been triaged for priority (run Code Optimization or Architectural Review first)

## Inputs

```json
{
  "findings_source": "docs/code-optimization/findings.json | docs/architectural-review/assessment.json | inline",
  "findings": [
    {
      "finding_id": "FIND-001",
      "category": "duplication | complexity | coupling | dead_code | anti_pattern",
      "severity": "critical | high | medium | low",
      "title": "Short description",
      "location": "module or file path (behaviour-level OK)",
      "recommendation": "What needs to change"
    }
  ],
  "constraints": {
    "max_commits_per_step": 1,
    "must_not_break_public_api": true,
    "test_coverage_required_before_refactor": true
  }
}
```

## Method

### Step 1: Group Related Findings

Cluster findings that are causally related or that must be changed together to avoid breaking the codebase:

- Findings in the same module or affecting the same abstraction boundary go together
- Findings where fixing A enables fixing B (dependency order) are sequenced, not grouped
- Independent findings become separate commits

### Step 2: Sequence the Commits

Order the groups following these safety rules:

1. **Test coverage first** — If a finding touches untested code, the first commit in the sequence adds tests for the current (broken) behaviour. This makes the subsequent refactor verifiable.
2. **Leaf nodes before root nodes** — Fix the most deeply nested or dependent components first before touching the callers
3. **Extract before delete** — When eliminating duplication, extract the shared abstraction first, update callers next, delete the duplicates last
4. **Interface before implementation** — When changing a contract, update the interface/signature first, then update each implementation
5. **Small commits, one concern per commit** — Each commit changes exactly one thing. Never combine a rename with a logic change.

### Step 3: Write Each Commit Step

For each commit in the sequence, produce:

```json
{
  "step": 1,
  "commit_type": "test | refactor