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: | Dimension | Questions to Ask | | --------------- | ----------------------------------------------------------------------------------------------------- | | Correctness | Are there edge cases not tested? Does documentation match actual behaviour? | | Readability | Is intent clear at a glance? Are names self-explanatory? Are surprising choices explained? | | Testability | Can behaviour be verified without spawning a process? Are unit and integration paths both covered? | | Maintainability | Are concerns separated? Is any function too long or doing too many things? | | Modularity | Are abstractions reusable? Are conversions done in idiomatic places (e.g. `From` impls)? | | Documentation | Are public APIs documented? Are non-obvious invariants or contract details captured in spec and code? | ### 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: | Impact | Meaning | | ------ | --------------------------------------------------------- | | High | Correctness, observability, or user-facing contract issue | | Medium | Developer experience, maintainability, clarity | | Low | Nice-to-have polish or future-proofing | | Effort | Meaning | | ------- | --------------------------------------------------- | | Trivial | One-liner or wording change, no logic involved | | Low | Small, self-contained code or doc change (< 1 hour) | | Medium | Moderate refactor or new abstraction (1–4 hours) | | High | Significant new code, e.g. mock server (> 4 hours) | ### 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. ```bash mkdir docs/refactor-plans/drafts/{short-description} touch docs/refactor-plans/drafts/{short-description}/REFACTOR-PLAN.md ``` Use the template at [docs/templates/REFACTOR-PLAN.md](../../../../../docs/templates/REFACTOR-PLAN.md). Name the record directory `{related-artifact-short-description}`. Its primary document is always `REFACTOR-PLAN.md`; keep related evidence and reports beside it in the same directory. Example: `1178-monitor-udp-post-implementation-improvements/REFACTOR-PLAN.md` Each item heading uses a checkbox and an impact/effort label: ```markdown ### 1. [ ] {Title} [HIGH impact / TRIVIAL effort] ``` The execution table also has a `Status` column with `[ ]`: ```markdown | 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: ```bash git mv docs/refactor-plans/drafts/{short-description} \ docs/refactor-plans/open/{short-description} ``` ```bash 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/`: ```bash git mv docs/refactor-plans/open/{short-description} \ docs/refactor-plans/closed/{short-description} 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. ## Layout and Lifecycle Each refactor plan uses a directory named `{related-artifact-short-description}` and primary file `REFACTOR-PLAN.md`. | Lifecycle stage | Primary-plan path | | --------------- | ----------------------------------------------------------------- | | Being written | `docs/refactor-plans/drafts/<short-description>/REFACTOR-PLAN.md` | | In progress | `docs/refactor-plans/open/<short-description>/REFACTOR-PLAN.md` | | All done | `docs/refactor-plans/closed/<short-description>/REFACTOR-PLAN.md` | ## Relationship to Other Artifacts | Artifact | When to Use Instead | | ------------- | ----------------------------------------------------------------- | | Issue spec | When the improvement is a bug fix or new feature | | ADR | When the improvement requires documenting an architectural choice | | Refactor plan | When improvements are quality gaps with no new functionality |