Refactor Planning
Purpose
Plan a refactor that improves structure or quality without changing external behavior, in small reversible steps backed by tests. Produces a refactor work item in ../../work-items/refactors/.
When to Use
- Request classified as refactor, or cleanup enabling later work.
- Not when behavior should change (that's
feature-planning) or when fixing a defect (bug-investigation).
Inputs
- The target code and its current tests.
- The improvement goal (readability, decoupling, performance-neutral cleanup).
Discovery Questions
- What is the concrete improvement goal, and how is "better" judged?
- Does adequate test coverage exist to prove behavior is preserved?
- What is the blast radius; who depends on this code?
- Can it be done in small, independently verifiable steps?
Responsibilities
- Audit the target and its dependents.
- Confirm/establish test coverage before touching risky areas.
- Plan small, reversible, behavior-preserving steps.
- Define verification that behavior is unchanged at each step.
- Record the refactor work item.
Required Workflow
- Read the target + dependents + tests. A refactor with zero observable change needs no new Gherkin — the existing scenarios and tests prove it unchanged. If any observable behavior changes (an API field, an error, a response), it is a feature: specify it first (
../../system/GHERKIN_RULES.md).
- If coverage is inadequate, plan to add characterization tests first.
- Break the refactor into small reversible steps.
- Define per-step verification (tests green, behavior identical).
- Record the work item (steps, risk, verification); on a tracked project, each step or group becomes a
TECH- task scheduled by project-management (../../system/PROJECT_MANAGEMENT_RULES.md).
Decision Rules
- Behavior-preserving by definition — any behavior change reclassifies as a feature.
- Restructuring is not replacing: keep the technology unless the refactor's stated goal is that change (
../../system/TECHNOLOGY_GOVERNANCE_RULES.md §3).
- Add tests before refactoring under-covered risky code.
- Prefer many small steps over a big-bang rewrite.
- If risk is high and value low, recommend deferring.
Rules
- Do not change observable behavior.
- Keep each step independently verifiable and revertible.
- Preserve public contracts unless the plan explicitly versions them.
Anti-Patterns
- Big-bang rewrite with no rollback path.
- Refactoring untested, risky code without adding tests first.
- Slipping behavior changes into a "refactor."
Validation Checklist
Definition of Done
A recorded refactor work item with a clear goal, sufficient test coverage (or a plan to add it), small reversible steps, and per-step verification proving behavior is unchanged.
Related Skills
existing-project-audit, testing-strategy, task-planning, code-review, performance-review (if perf-motivated), project-orchestrator, project-management.
Related Knowledge
../../knowledge/ (module contracts, invariants).
Related References
../../references/<topic>/ for patterns if needed.
Context Loading Guidance
- Requires: target code, dependents, current tests, the goal.
- Does not require: unrelated modules, the full reference tree, unrelated skills.
- May load:
testing-strategy (coverage), performance-review (if perf-driven).
- Stop when: steps + verification are recorded.
Token Efficiency Guidance
Scope reading to the target and its direct dependents. Capture steps tersely; rely on tests as the verification record rather than prose.
1---2name: refactor-planning3description: Use to plan a behavior-preserving structural improvement — audit the target, ensure test coverage exists, plan small reversible steps, and verify behavior is unchanged. Any intended behavior change is a feature, not a refactor.4metadata:5 source: https://skillmd.com/skills/ahtishamshahzad/refactor-planning6---78# Refactor Planning910## Purpose1112Plan a refactor that improves structure or quality **without changing external behavior**, in small reversible steps backed by tests. Produces a refactor work item in `../../work-items/refactors/`.1314## When to Use1516- Request classified as **refactor**, or cleanup enabling later work.17- **Not** when behavior should change (that's `feature-planning`) or when fixing a defect (`bug-investigation`).1819## Inputs2021- The target code and its current tests.22- The improvement goal (readability, decoupling, performance-neutral cleanup).2324## Discovery Questions2526- What is the concrete improvement goal, and how is "better" judged?27- Does adequate test coverage exist to prove behavior is preserved?28- What is the blast radius; who depends on this code?29- Can it be done in small, independently verifiable steps?3031## Responsibilities3233- **Audit** the target and its dependents.34- **Confirm/establish test coverage** before touching risky areas.35- Plan **small, reversible, behavior-preserving steps**.36- Define **verification** that behavior is unchanged at each step.37- Record the refactor work item.3839## Required Workflow40411. Read the target + dependents + tests. A refactor with zero observable change needs no new Gherkin — the existing scenarios and tests prove it unchanged. If any observable behavior changes (an API field, an error, a response), it is a feature: specify it first (`../../system/GHERKIN_RULES.md`).422. If coverage is inadequate, plan to add characterization tests first.433. Break the refactor into small reversible steps.444. Define per-step verification (tests green, behavior identical).455. Record the work item (steps, risk, verification); on a tracked project, each step or group becomes a `TECH-` task scheduled by `project-management` (`../../system/PROJECT_MANAGEMENT_RULES.md`).4647## Decision Rules4849- Behavior-preserving by definition — any behavior change reclassifies as a feature.50- Restructuring is not replacing: keep the technology unless the refactor's stated goal is that change (`../../system/TECHNOLOGY_GOVERNANCE_RULES.md` §3).51- Add tests before refactoring under-covered risky code.52- Prefer many small steps over a big-bang rewrite.53- If risk is high and value low, recommend deferring.5455## Rules5657- Do not change observable behavior.58- Keep each step independently verifiable and revertible.59- Preserve public contracts unless the plan explicitly versions them.6061## Anti-Patterns6263- Big-bang rewrite with no rollback path.64- Refactoring untested, risky code without adding tests first.65- Slipping behavior changes into a "refactor."6667## Validation Checklist6869- [ ] Improvement goal explicit.70- [ ] Coverage confirmed or characterization tests planned.71- [ ] Steps small and reversible.72- [ ] Per-step verification defined.73- [ ] Behavior-preservation guaranteed by tests.7475## Definition of Done7677A recorded refactor work item with a clear goal, sufficient test coverage (or a plan to add it), small reversible steps, and per-step verification proving behavior is unchanged.7879## Related Skills8081`existing-project-audit`, `testing-strategy`, `task-planning`, `code-review`, `performance-review` (if perf-motivated), `project-orchestrator`, `project-management`.8283## Related Knowledge8485`../../knowledge/` (module contracts, invariants).8687## Related References8889`../../references/<topic>/` for patterns if needed.9091## Context Loading Guidance9293- **Requires:** target code, dependents, current tests, the goal.94- **Does not require:** unrelated modules, the full reference tree, unrelated skills.95- **May load:** `testing-strategy` (coverage), `performance-review` (if perf-driven).96- **Stop when:** steps + verification are recorded.9798## Token Efficiency Guidance99100Scope reading to the target and its direct dependents. Capture steps tersely; rely on tests as the verification record rather than prose.