create-refactor-plan

Creating Refactor Plans

When to Write a Refactor Plan

Write a refactor plan when:

• A completed implementation has known quality gaps that are not blocking but worth tracking.
• A code review, post-implementation audit, or routine quality check identifies improvements across multiple dimensions (readability, testability, maintainability, modularity, docs).
• The improvements are too numerous or varied to address in a single commit but collectively deserve a structured approach.

Do not write a refactor plan for:

• A single trivial fix — just fix it in place.
• Bug fixes — those belong in issue specs (docs/templates/ISSUE.md).
• Architectural decisions — those belong in ADRs (docs/templates/ADR.md).

Workflow Overview

1. Identify quality gaps by auditing the code, spec, and tests.
2. Decompose gaps into discrete, independently completable items.
3. Order items by impact vs effort (highest impact / lowest effort first).
4. Draft the plan using the template.
5. Run linters and fix any issues.
6. Commit the plan.
7. Implement items one at a time, ticking checkboxes as each is done.
8. Revisit the plan after implementation to evaluate whether the template and skill need improvements.

Step-by-Step Process

Step 1: Identify and Categorize Quality Gaps

Review the following dimensions systematically:

Step 2: Write Each Item

Each item in the plan must contain:

• Problem: what is wrong and why it matters — be specific (name files, functions, line ranges).
• Files: the files affected.
• Change: what exactly changes — prefer concrete before/after examples over vague descriptions.

Use the effort and impact labels consistently:

Step 3: Order Items

Sort items in the plan and in the execution table by:

1. Highest impact first.
2. Lowest effort first within the same impact band.

This ensures the most valuable, cheapest improvements are visible and tackled first.

Step 4: Create the Plan File

Plans follow the same drafts/ → open/ → closed/ lifecycle as issue specs.

touch docs/refactor-plans/drafts/{short-description}.md

Use the template at docs/templates/REFACTOR-PLAN.md.

Naming convention: {related-artifact-short-description}.md

Example: 1178-monitor-udp-post-implementation-improvements.md

Each item heading uses a checkbox and an impact/effort label:

### 1. [ ] {Title} [HIGH impact / TRIVIAL effort]

The execution table also has a Status column with [ ]:

| 1 | [ ] | {Item} | High | Trivial |

To mark an item done, flip [ ] → [x] in both the heading and the table row.

Step 5: Validate and Commit

Move the plan from drafts/ to open/ when implementation starts:

git mv docs/refactor-plans/drafts/{filename}.md docs/refactor-plans/open/{filename}.md

linter all    # Must pass

git add docs/refactor-plans/
git commit -S -m "docs({scope}): add refactor plan for {description}"

Step 6: Implement and Track Progress

Work through items in order. After completing each item:

1. Flip [ ] → [x] in the item heading.
2. Flip [ ] → [x] in the execution table row.
3. Run linter all and fix any new issues.
4. Commit the implementation and the updated plan together.

When all items are done, move the plan to closed/:

git mv docs/refactor-plans/open/{filename}.md docs/refactor-plans/closed/{filename}.md
git commit -S -m "docs({scope}): close refactor plan for {description}"

Step 7: Revisit the Template and Skill

After implementing all items, evaluate:

• Did the template structure make items easy to write and track?
• Were the impact/effort labels consistently interpreted?
• Is anything missing that would have made the plan more useful?

Update docs/templates/REFACTOR-PLAN.md and this skill file if improvements are identified.

Naming Convention

File name format: {related-artifact-short-description}.md

Relationship to Other Artifacts